@bingjiang0611/rotom 0.1.0-alpha.0

package/extensions/third-party/node_modules/pi-subagents/src/shared/types.ts

@@ -0,0 +1,2307 @@
+/**
+ * Type definitions for the subagent extension
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import type { AgentConfig } from "../agents/agents.ts";
+import type { FSWatcher } from "node:fs";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelScopeConfig } from "../runs/shared/model-scope.ts";
+import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
+import type { AuthorityPolicyConfig } from "../policy/authority.ts";
+import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
+
+// ============================================================================
+// Basic Types
+// ============================================================================
+
+export interface MaxOutputConfig {
+	bytes?: number;
+	lines?: number;
+}
+
+export type OutputMode = "inline" | "file-only";
+
+export type AcceptanceRole = "read-only" | "writer";
+
+export type JsonSchemaObject = Record<string, unknown>;
+
+export interface ChainOutputMapEntry {
+	text: string;
+	structured?: unknown;
+	agent: string;
+	stepIndex: number;
+}
+
+export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
+
+export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "paused" | "stopped" | "detached" | "rejected";
+
+export interface WorkflowGraphNode {
+	id: string;
+	kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
+	agent?: string;
+	phase?: string;
+	label: string;
+	status: WorkflowNodeStatus;
+	flatIndex?: number;
+	stepIndex?: number;
+	children?: WorkflowGraphNode[];
+	dynamic?: {
+		sourceOutput: string;
+		sourcePath: string;
+		itemName: string;
+		maxItems?: number;
+		collectAs?: string;
+	};
+	itemKey?: string;
+	outputName?: string;
+	structured?: boolean;
+	acceptanceStatus?: AcceptanceLedgerStatus;
+	error?: string;
+}
+
+export interface WorkflowGraphSnapshot {
+	runId: string;
+	mode: SubagentRunMode;
+	phases: Array<{ title: string; nodeIds: string[] }>;
+	nodes: WorkflowGraphNode[];
+	currentNodeId?: string;
+}
+
+export interface SavedOutputReference {
+	path: string;
+	bytes: number;
+	lines: number;
+	message: string;
+}
+
+interface TruncationResult {
+	text: string;
+	truncated: boolean;
+	originalBytes?: number;
+	originalLines?: number;
+	artifactPath?: string;
+}
+
+export interface Usage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+}
+
+export interface TurnBudgetConfig {
+	maxTurns: number;
+	graceTurns?: number;
+}
+
+export interface ResolvedTurnBudget {
+	maxTurns: number;
+	graceTurns: number;
+}
+
+export interface ToolBudgetConfig {
+	soft?: number;
+	hard: number;
+	block?: string[] | "*";
+}
+
+export interface ResolvedToolBudget {
+	soft?: number;
+	hard: number;
+	block: string[] | "*";
+}
+
+export type ToolBudgetOutcome = "within-budget" | "soft-reached" | "hard-blocked";
+
+export interface ToolBudgetState extends ResolvedToolBudget {
+	outcome: ToolBudgetOutcome;
+	toolCount: number;
+	softReachedAt?: number;
+	hardReachedAt?: number;
+	blockedTool?: string;
+}
+
+export type TurnBudgetOutcome = "within-budget" | "wrap-up-requested" | "termination-deferred" | "exceeded";
+
+export interface TurnBudgetState extends ResolvedTurnBudget {
+	outcome: TurnBudgetOutcome;
+	turnCount: number;
+	wrapUpRequestedAtTurn?: number;
+	terminationDeferredAtTurn?: number;
+	exceededAtTurn?: number;
+}
+
+export interface TokenUsage {
+	input: number;
+	output: number;
+	total: number;
+}
+
+export type ActivityState = "active_long_running" | "needs_attention";
+export type ControlEventType = "active_long_running" | "needs_attention";
+export type ControlNotificationChannel = "event" | "async" | "intercom";
+
+export interface ControlConfig {
+	enabled?: boolean;
+	needsAttentionAfterMs?: number;
+	activeNoticeAfterMs?: number;
+	activeNoticeAfterTurns?: number;
+	activeNoticeAfterTokens?: number;
+	failedToolAttemptsBeforeAttention?: number;
+	notifyOn?: ControlEventType[];
+	notifyChannels?: ControlNotificationChannel[];
+}
+
+export interface ResolvedControlConfig {
+	enabled: boolean;
+	needsAttentionAfterMs: number;
+	activeNoticeAfterMs: number;
+	activeNoticeAfterTurns?: number;
+	activeNoticeAfterTokens?: number;
+	failedToolAttemptsBeforeAttention: number;
+	notifyOn: ControlEventType[];
+	notifyChannels: ControlNotificationChannel[];
+}
+
+/**
+ * Smart completion batching for async-completion notifications. Successful
+ * sibling completions are held briefly so they arrive as one grouped message;
+ * failure and attention signals bypass grouping and always fire immediately.
+ */
+export interface CompletionBatchConfig {
+	enabled?: boolean;
+	/** Idle window after each arrival; resets on every new item. */
+	debounceMs?: number;
+	/** Hard cap measured from the first item in a group. */
+	maxWaitMs?: number;
+	/** Shorter idle window for straggler groups. */
+	stragglerDebounceMs?: number;
+	/** Shorter hard cap for straggler groups. */
+	stragglerMaxWaitMs?: number;
+	/** Arrivals within this window after an emit join a straggler group. */
+	stragglerWindowMs?: number;
+}
+
+export interface WaitToolConfigObject {
+	enabled?: boolean;
+}
+
+export type WaitToolConfig = boolean | WaitToolConfigObject;
+
+export interface ControlEvent {
+	/** Stable across delivery channels and replay; not a supervisor request ID. */
+	id?: string;
+	type: ControlEventType;
+	from?: ActivityState;
+	to: ActivityState;
+	ts: number;
+	agent: string;
+	index?: number;
+	runId: string;
+	nestedRunId?: string;
+	nestingPath?: NestedRunAddress["path"];
+	message: string;
+	reason?: "idle" | "completion_guard" | "active_long_running" | "tool_failures" | "supervisor_request" | "time_threshold" | "turn_threshold" | "token_threshold" | "tool_open_threshold";
+	turns?: number;
+	tokens?: number;
+	toolCount?: number;
+	currentTool?: string;
+	currentToolDurationMs?: number;
+	currentPath?: string;
+	elapsedMs?: number;
+	recentFailureSummary?: string;
+	workflowKey?: string;
+	phase?: string;
+	label?: string;
+	taskPreview?: string;
+}
+
+export type SubagentResultStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
+export type SubagentOutputState = "present" | "absent" | "unknown";
+export type SubagentRunMode = "single" | "parallel" | "chain" | "workflow";
+export type SubagentResultMode = SubagentRunMode;
+
+export interface ParallelHandoffPatch {
+	path: string;
+	branch: string;
+	changed: boolean;
+	diffStat: string;
+	filesChanged: number;
+	insertions: number;
+	deletions: number;
+	error?: string;
+}
+
+export interface ParallelHandoffChild {
+	index: number;
+	taskIndex: number;
+	agent: string;
+	status: SubagentResultStatus;
+	summary: string;
+	outputPath?: string;
+	structuredOutput?: unknown;
+	structuredOutputPath?: string;
+	sessionPath?: string;
+	patch: ParallelHandoffPatch;
+}
+
+export interface ParallelHandoffCleanupTask {
+	index: number;
+	path: string;
+	branch: string;
+	worktreeRemoved: boolean;
+	branchRemoved: boolean;
+	preserved?: boolean;
+	reason?: string;
+	errors?: string[];
+}
+
+export interface ParallelHandoffGroup {
+	stepIndex: number;
+	baseCommit: string;
+	repoRoot: string;
+	children: ParallelHandoffChild[];
+	cleanup: {
+		state: "complete" | "partial";
+		tasks: ParallelHandoffCleanupTask[];
+		pruned: boolean;
+		errors?: string[];
+	};
+}
+
+export interface ParallelHandoffManifest {
+	version: 1;
+	runId: string;
+	mode: "single" | "parallel" | "chain";
+	source: "foreground" | "async";
+	cwd: string;
+	createdAt: number;
+	updatedAt: number;
+	groups: ParallelHandoffGroup[];
+}
+
+export interface ParallelHandoffReference {
+	version: 1;
+	path: string;
+	groupCount: number;
+	childCount: number;
+	changedPatches: number;
+	cleanupState: "complete" | "partial";
+}
+
+export interface AgentContract {
+	version: 1;
+}
+
+export type ChainGateLayer = "execution" | "acceptance";
+
+export type ExecutionProjectionStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
+
+export interface ExecutionProjection {
+	status: ExecutionProjectionStatus;
+	success: boolean;
+	exitCode: number;
+	error?: string;
+	interrupted?: boolean;
+	timedOut?: boolean;
+	stopped?: boolean;
+	detached?: boolean;
+}
+
+export interface ReviewProjection {
+	status: "not-requested" | "review-required" | "reviewed" | "blockers";
+	findings?: AcceptanceReviewResult["findings"];
+}
+
+export interface FileMutationEffect {
+	status: "not-requested" | "not-applicable" | "observed" | "missing";
+	expected: boolean;
+	attempted: boolean;
+	message?: string;
+	resolvedBy?: "llm-intent-arbiter";
+}
+
+export interface EffectsProjection {
+	fileMutation?: FileMutationEffect;
+}
+
+export const SUBAGENT_LIFECYCLE_ARTIFACT_VERSION = 3;
+export type SubagentLifecycleArtifactVersion = typeof SUBAGENT_LIFECYCLE_ARTIFACT_VERSION;
+
+export type ProcessTerminalState = "pending" | "observed" | "unknown" | "not-started";
+export type ProcessTerminalReason =
+	| "observer-unavailable"
+	| "runner-candidate-missing"
+	| "runner-instance-mismatch"
+	| "writer-close-unverified"
+	| "process-tree-unverified"
+	| "canonical-session-unavailable"
+	| "canonical-session-lease-active"
+	| "canonical-session-release-unverified"
+	| "proof-write-failed"
+	| "stale-repair";
+
+export interface RunnerProcessInstanceExitV1 {
+	processInstanceId: string;
+	kind: "runner";
+	closeObservedAt: number;
+	exitCode: number | null;
+	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";
+	attempt: number;
+	closeObservedAt: number;
+	exitCode: number | null;
+	signal: string | null;
+	processTree: ProcessTreeTerminalV1;
+}
+
+export type ProcessInstanceExitV1 = RunnerProcessInstanceExitV1 | PiWriterProcessInstanceExitV1;
+
+export interface CanonicalSessionTerminalV1 {
+	canonicalSessionId: string;
+	leaseDisposition: "released" | "not-held";
+	freeAtObservation: true;
+	canonicalSessionLeaseReleased?: true;
+}
+
+interface ProcessTerminalBaseV1 {
+	version: 1;
+	runId: string;
+	childIndex?: number;
+	runnerProcessInstanceId: string;
+	observedAt?: number;
+	reason?: ProcessTerminalReason;
+	resumeDisposition?: "resumable" | "non-resumable" | "unavailable";
+}
+
+export type ProcessTerminalV1 =
+	| (ProcessTerminalBaseV1 & { state: "pending" | "not-started" })
+	| (ProcessTerminalBaseV1 & {
+		state: "observed";
+		observedAt: number;
+		instances: ProcessInstanceExitV1[];
+		canonicalSession?: CanonicalSessionTerminalV1;
+	})
+	| (ProcessTerminalBaseV1 & {
+		state: "unknown";
+		reason: ProcessTerminalReason;
+		diagnostic?: string;
+	});
+
+/** Identifies the durable schedule that launched a run, so its completion is attributable. */
+export interface ScheduleOrigin {
+	id: string;
+	name?: string;
+}
+
+export type SteeringActionState = "delivered" | "scheduled" | "pending" | "partial" | "recovered" | "failed";
+export type SteeringTargetState = "scheduled" | "pending" | "routed" | "queued" | "delivered" | "late" | "failed" | "recovered";
+
+export interface SteeringTargetStatus {
+	index: number;
+	state: SteeringTargetState;
+	routedAt?: number;
+	deliveredAt?: number;
+	lateDeliveredAt?: number;
+	failedAt?: number;
+	recoveredAt?: number;
+	reason?: string;
+	replacementRunId?: string;
+}
+
+export interface SteeringRequestStatus {
+	id: string;
+	requestedAt: number;
+	source?: string;
+	messagePreview: string;
+	targets: SteeringTargetStatus[];
+}
+
+export interface SteeringStatus {
+	requested: number;
+	scheduled: number;
+	pending: number;
+	delivered: number;
+	failed: number;
+	recovered: number;
+	lastRequestedAt?: number;
+	lastDeliveredAt?: number;
+	recent: SteeringRequestStatus[];
+}
+
+export interface SteerActionTarget {
+	index: number;
+	state: SteeringTargetState;
+	deliveredAt?: number;
+	lateDeliveredAt?: number;
+	reason?: string;
+	replacementRunId?: string;
+}
+
+export interface SteerActionResult {
+	requestId: string;
+	state: SteeringActionState;
+	deliveryStatus: "delivered" | "queued";
+	sourceRunId: string;
+	replacementRunId?: string;
+	targets: SteerActionTarget[];
+}
+
+export interface SteeringNotice {
+	type: "subagent.steering.notice";
+	ts: number;
+	runId: string;
+	requestId: string;
+	state: "failed" | "partial" | "recovered";
+	message: string;
+	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;
+	sessionFile?: string;
+	cwd: string;
+	model?: string;
+	modelOverrideFromParent?: boolean;
+	fallbackModels?: string[];
+	thinking?: string;
+	tools?: string[];
+	extensions?: string[];
+	subagentOnlyExtensions?: string[];
+	mcpDirectTools?: string[];
+	systemPrompt?: string;
+	systemPromptMode: "append" | "replace";
+	inheritProjectContext: boolean;
+	inheritSkills: boolean;
+	skills?: string[];
+	skillPath?: string[];
+	agentFilePath?: string;
+	completionGuard?: boolean;
+	memory?: { scope: "project" | "user"; path: string };
+	outputPath?: string;
+	outputMode: "inline" | "file-only";
+	structuredOutputSchema?: JsonSchemaObject;
+	acceptance?: AcceptanceInput;
+	controlConfig?: ResolvedControlConfig;
+	/** Raw per-run bridge override. Omitted descriptors continue to use global config. */
+	intercomBridge?: IntercomBridgeConfig;
+	absoluteDeadlineAt?: number;
+	initialTurnBudget?: ResolvedTurnBudget;
+	initialToolBudget?: ResolvedToolBudget;
+	maxSubagentDepth: number;
+	maxOutput?: MaxOutputConfig;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+	share: boolean;
+	sessionDir?: string;
+	artifactsDir?: string;
+	artifactConfig?: ArtifactConfig;
+}
+
+export type PublicNestedStepSummary = Pick<
+	NestedStepSummary,
+	"agent" | "status" | "model" | "thinking" | "sessionFile" | "transcriptPath" | "transcriptError" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "startedAt" | "endedAt" | "error" | "timedOut" | "stopped"
+> & {
+	children?: PublicNestedRunSummary[];
+};
+
+export type CostSummary = {
+	inputTokens: number;
+	outputTokens: number;
+	costUsd: number;
+};
+
+export type PublicNestedRunSummary = Pick<
+	NestedRunSummary,
+	"id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "model" | "thinking" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "totalTokens" | "totalCost" | "startedAt" | "endedAt" | "lastUpdate" | "error" | "timeoutMs" | "deadlineAt" | "timedOut" | "stopped" | "turnBudget" | "turnBudgetExceeded" | "wrapUpRequested"
+> & {
+	steps?: PublicNestedStepSummary[];
+	children?: PublicNestedRunSummary[];
+};
+
+export interface SubagentResultIntercomChild {
+	agent: string;
+	/** Process/lifecycle status. It does not establish semantic task completion. */
+	status: SubagentResultStatus;
+	/** Whether the child produced substantive output before its process ended. */
+	outputState?: SubagentOutputState;
+	summary: string;
+	index?: number;
+	artifactPath?: string;
+	sessionPath?: string;
+	intercomTarget?: string;
+	children?: PublicNestedRunSummary[];
+}
+
+export interface SubagentResultIntercomPayload {
+	to: string;
+	message: string;
+	requestId?: string;
+	runId: string;
+	mode: SubagentRunMode;
+	status: SubagentResultStatus;
+	summary: string;
+	source: "foreground" | "async";
+	children: SubagentResultIntercomChild[];
+	asyncId?: string;
+	asyncDir?: string;
+	chainSteps?: number;
+	agent?: string;
+	index?: number;
+	artifactPath?: string;
+	sessionPath?: string;
+	parallelHandoff?: ParallelHandoffReference;
+}
+
+// ============================================================================
+// Progress Tracking
+// ============================================================================
+
+export interface ChildWatchdogProgress {
+	phase: "idle" | "reviewing" | "autofollow" | "settling" | "stale" | "failed";
+	seq: number;
+	lastUpdate: number;
+	followUpPending: boolean;
+	reason?: string;
+	timedOut?: boolean;
+}
+
+export interface AgentProgress {
+	index: number;
+	agent: string;
+	status: "pending" | "running" | "completed" | "failed" | "detached";
+	activityState?: ActivityState;
+	task: string;
+	skills?: string[];
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	recentTools: Array<{ tool: string; args: string; endMs: number }>;
+	recentOutput: string[];
+	toolCount: number;
+	turnCount?: number;
+	tokens: number;
+	/** Resolved launch model/effort and split usage for public live projections. */
+	model?: string;
+	thinking?: string;
+	inputTokens?: number;
+	outputTokens?: number;
+	durationMs: number;
+	error?: string;
+	failedTool?: string;
+	watchdog?: ChildWatchdogProgress;
+}
+
+export interface ToolCallSummary {
+	text: string;
+	expandedText: string;
+}
+
+interface ProgressSummary {
+	index?: number;
+	agent?: string;
+	status?: AgentProgress["status"];
+	activityState?: ActivityState;
+	skills?: string[];
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentToolStartedAt?: number;
+	recentTools?: Array<{ tool: string; args: string; endMs: number }>;
+	recentOutput?: string[];
+	toolCount: number;
+	tokens: number;
+	model?: string;
+	thinking?: string;
+	durationMs: number;
+}
+
+// ============================================================================
+// Results
+// ============================================================================
+
+export interface ModelAttempt {
+	model: string;
+	success: boolean;
+	exitCode?: number | null;
+	error?: string;
+	usage?: Usage;
+}
+
+export type AcceptanceLevel = "auto" | "none" | "attested" | "checked" | "verified";
+
+export type AcceptanceEvidenceKind =
+	| "changed-files"
+	| "tests-added"
+	| "commands-run"
+	| "validation-output"
+	| "residual-risks"
+	| "no-staged-files"
+	| "diff-summary"
+	| "review-findings"
+	| "manual-notes";
+
+export interface AcceptanceGate {
+	id: string;
+	must: string;
+	evidence?: AcceptanceEvidenceKind[];
+	severity?: "required" | "recommended";
+}
+
+export interface AcceptanceVerifyCommand {
+	id: string;
+	command: string;
+	timeoutMs?: number;
+	cwd?: string;
+	env?: Record<string, string>;
+	allowFailure?: boolean;
+}
+
+export interface AcceptanceReviewGate {
+	agent?: string;
+	focus?: string;
+	required?: boolean;
+}
+
+export interface AcceptanceConfig {
+	level?: AcceptanceLevel;
+	criteria?: Array<string | AcceptanceGate>;
+	evidence?: AcceptanceEvidenceKind[];
+	verify?: AcceptanceVerifyCommand[];
+	review?: AcceptanceReviewGate | false;
+	stopRules?: string[];
+	reason?: string;
+}
+
+/** Bare "none" and "verified" are not accepted; verified policies require object form with runtime commands. */
+export type AcceptanceInput = Exclude<AcceptanceLevel, "none" | "verified"> | false | AcceptanceConfig;
+
+export interface ResolvedAcceptanceGate extends AcceptanceGate {
+	id: string;
+	must: string;
+	evidence: AcceptanceEvidenceKind[];
+	severity: "required" | "recommended";
+}
+
+export interface ResolvedAcceptanceConfig {
+	level: Exclude<AcceptanceLevel, "auto">;
+	explicit: boolean;
+	inferredReason: string[];
+	criteria: ResolvedAcceptanceGate[];
+	evidence: AcceptanceEvidenceKind[];
+	verify: AcceptanceVerifyCommand[];
+	review?: AcceptanceReviewGate | false;
+	stopRules: string[];
+	reason?: string;
+}
+
+export interface AcceptanceReport {
+	criteriaSatisfied?: Array<{
+		id?: string;
+		status: "satisfied" | "not-satisfied" | "not-applicable";
+		evidence: string;
+	}>;
+	changedFiles?: string[];
+	testsAddedOrUpdated?: string[];
+	commandsRun?: Array<{
+		command: string;
+		result: "passed" | "failed" | "not-run";
+		summary: string;
+	}>;
+	validationOutput?: string[];
+	residualRisks?: string[];
+	noStagedFiles?: boolean;
+	diffSummary?: string;
+	reviewFindings?: string[];
+	manualNotes?: string;
+	notes?: string;
+}
+
+export type AcceptanceRuntimeCheckStatus = "passed" | "failed" | "not-applicable";
+
+export interface AcceptanceRuntimeCheck {
+	id: string;
+	status: AcceptanceRuntimeCheckStatus;
+	message: string;
+}
+
+export interface AcceptanceVerifyResult {
+	id: string;
+	command: string;
+	cwd?: string;
+	exitCode: number | null;
+	status: "passed" | "failed" | "timed-out" | "allowed-failure";
+	stdout?: string;
+	stderr?: string;
+	durationMs: number;
+	artifactPath?: string;
+	cacheKey?: string;
+	memoized?: boolean;
+	envKeys?: string[];
+	envHash?: string;
+	workspaceState?: {
+		kind: "git-tracked";
+		repoRoot: string;
+		cwdRelative: string;
+		head: string;
+		diffHash: string;
+	};
+	artifactError?: string;
+}
+
+export interface AcceptanceReviewResult {
+	status: "review-required" | "reviewed" | "blockers";
+	findings: Array<{
+		severity: "blocker" | "non-blocking";
+		file?: string;
+		issue: string;
+		rationale: string;
+	}>;
+}
+
+export type AcceptanceEvidenceStatus =
+	| "pending"
+	| "not-required"
+	| "claimed"
+	| "attested"
+	| "checked"
+	| "verified"
+	| "rejected";
+
+export type AcceptanceLedgerStatus =
+	| AcceptanceEvidenceStatus
+	| "review-required"
+	| "reviewed"
+	| "accepted";
+
+export interface AcceptanceLedger {
+	status: AcceptanceLedgerStatus;
+	evidenceStatus: AcceptanceEvidenceStatus;
+	explicit: boolean;
+	effectiveAcceptance: ResolvedAcceptanceConfig;
+	inferredReason: string[];
+	criteria: ResolvedAcceptanceGate[];
+	childReport?: AcceptanceReport;
+	childReportParseError?: string;
+	runtimeChecks: AcceptanceRuntimeCheck[];
+	verifyRuns: AcceptanceVerifyResult[];
+	reviewResult?: AcceptanceReviewResult;
+	parentDecision?: {
+		status: "accepted" | "rejected";
+		at: string;
+		reason?: string;
+	};
+}
+
+export interface ProtocolOutputLimit {
+	code: "protocol_output_limit";
+	stream: "stdout" | "stderr";
+	limitBytes: number;
+	observedBytes: number;
+	diagnosticPrefix: string;
+	diagnosticTail: string;
+}
+
+export interface LaunchResolvedChildExtensionsV1 {
+	version: 1;
+	/** This is parent-resolved launch intent, not child-runtime acknowledgement that extensions loaded. */
+	source: "launch-resolved";
+	disableAmbientExtensions: boolean;
+	runtime: string[];
+	configured: string[];
+	effective: string[];
+	omitted: {
+		runtime: number;
+		configured: number;
+		effective: number;
+	};
+}
+
+export interface RuntimeAcknowledgedChildExtensionsV1 {
+	version: 1;
+	/** Best-effort child-runtime registration acknowledgement, not extension health. */
+	source: "child-runtime";
+	ids: string[];
+	omitted: number;
+}
+
+export interface UsageBudgetLimitConfig {
+	soft?: number;
+	hard: number;
+}
+
+export interface UsageBudgetConfig {
+	tokens?: UsageBudgetLimitConfig;
+	costUsd?: UsageBudgetLimitConfig;
+}
+
+export interface UsageBudgetMetricState extends UsageBudgetLimitConfig {
+	used: number;
+	outcome: "within-budget" | "soft-exceeded" | "hard-exceeded";
+}
+
+export interface UsageBudgetState {
+	version: 1;
+	/** Enforced from usage reported by completed or streaming child runs; no reservation estimates. */
+	source: "reported";
+	tokens?: UsageBudgetMetricState;
+	costUsd?: UsageBudgetMetricState;
+	exhausted: boolean;
+	reason?: "tokens" | "costUsd";
+}
+
+export interface SingleResult {
+	/**
+	 * Stable child identity within the foreground run. Pair with Details.runId for
+	 * cross-run correlation. This is assigned in launch order, remains stable across
+	 * partial progress snapshots and the final result, and is independent of the
+	 * result row's array position.
+	 */
+	index: number;
+	agent: string;
+	task: string;
+	/** Resolved launch context for this child. */
+	context?: "fresh" | "fork";
+	exitCode: number;
+	processSignal?: string | null;
+	detached?: boolean;
+	detachedReason?: string;
+	interrupted?: boolean;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
+	messages?: Message[];
+	usage: Usage;
+	model?: string;
+	/** Effective thinking level used by this foreground child, when known. */
+	thinking?: string;
+	attemptedModels?: string[];
+	modelAttempts?: ModelAttempt[];
+	controlEvents?: ControlEvent[];
+	error?: string;
+	protocolError?: ProtocolOutputLimit;
+	sessionFile?: string;
+	skills?: string[];
+	skillsWarning?: string;
+	progress?: AgentProgress;
+	progressSummary?: ProgressSummary;
+	toolCalls?: ToolCallSummary[];
+	artifactPaths?: ArtifactPaths;
+	truncation?: TruncationResult;
+	finalOutput?: string;
+	/** Provenance-aware state for substantive child output, excluding synthetic lifecycle messages. */
+	outputState?: SubagentOutputState;
+	outputMode?: OutputMode;
+	savedOutputPath?: string;
+	outputReference?: SavedOutputReference;
+	outputSaveError?: string;
+	/** Best-effort metadata persistence failure; execution and receipt publication continue. */
+	metadataSaveError?: string;
+	structuredOutput?: unknown;
+	structuredOutputFailed?: boolean;
+	structuredOutputPath?: string;
+	structuredOutputSchemaPath?: string;
+	acceptance?: AcceptanceLedger;
+	agentContract?: AgentContract;
+	launchContractDigest?: string;
+	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+	execution?: ExecutionProjection;
+	review?: ReviewProjection;
+	effects?: EffectsProjection;
+	transcriptPath?: string;
+	transcriptError?: string;
+	children?: NestedRunSummary[];
+	watchdog?: ChildWatchdogProgress;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: SubagentCapabilityAudit;
+}
+
+export interface SpawnBudgetGrant {
+	sessionId: string;
+	amount: number;
+	grantedAt: number;
+	previousLimit: number;
+	limit: number;
+}
+
+export interface SpawnBudgetSnapshot {
+	used: number;
+	configuredLimit: number | null;
+	granted: number;
+	limit: number | null;
+	remaining: number | null;
+	grantRemaining: number | null;
+	grantHistory: SpawnBudgetGrant[];
+}
+
+/** Slim per-child projection of a terminal result payload, safe to surface in tool_result details. */
+export interface WaitCompletionChild {
+	agent?: string;
+	/** Child run identity where the producer records one (workflow children); artifact files are keyed by it. */
+	runId?: string;
+	success?: boolean;
+	outputState?: SubagentOutputState;
+	error?: string;
+	model?: string;
+	artifactPaths?: Partial<ArtifactPaths>;
+}
+
+/**
+ * Terminal completion observed for a run a subagent_wait call covered. Carries run
+ * identity and the artifact trail; output text stays in the tool result content.
+ */
+export interface WaitCompletion {
+	runId: string;
+	agent?: string;
+	mode?: string;
+	state?: string;
+	success?: boolean;
+	/** Versioned bounded output archive retained with the durable completion replay. */
+	archivePath?: string;
+	results?: WaitCompletionChild[];
+}
+
+export interface Details {
+	mode: SubagentResultMode | "management";
+	runId?: string;
+	/** Host tool-call id retained when it differs from the internal run id. */
+	toolCallId?: string;
+	/** Run-level context summary. "mixed" when children resolved to different modes. */
+	context?: "fresh" | "fork" | "mixed";
+	results: SingleResult[];
+	/**
+	 * Terminal completion payloads for runs this subagent_wait call observed
+	 * finishing. Async completions travel as result files that are consumed and
+	 * deleted after text delivery, so without this field their run and artifact
+	 * identity never reaches tool_result details.
+	 */
+	completions?: WaitCompletion[];
+	controlEvents?: ControlEvent[];
+	steering?: SteerActionResult;
+	asyncId?: string;
+	background?: boolean;
+	asyncDir?: string;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudget?: ResolvedTurnBudget;
+	toolBudget?: ResolvedToolBudget;
+	usageBudget?: UsageBudgetState;
+	progress?: AgentProgress[];
+	progressSummary?: ProgressSummary;
+	artifacts?: {
+		dir: string;
+		files: ArtifactPaths[];
+	};
+	truncation?: {
+		truncated: boolean;
+		originalBytes?: number;
+		originalLines?: number;
+		artifactPath?: string;
+	};
+	// Chain metadata for observability
+	chainAgents?: string[];      // Agent names in order, e.g., ["scout", "planner"]
+	totalSteps?: number;         // Total steps in chain
+	currentStepIndex?: number;   // 0-indexed current step (for running chains)
+	workflowGraph?: WorkflowGraphSnapshot;
+	outputs?: ChainOutputMap;
+	// Aggregated child usage across all agents in the run
+	totalChildUsage?: Usage;
+	// Aggregated cost across all agents in the run
+	totalCost?: CostSummary;
+	spawnBudget?: SpawnBudgetSnapshot;
+	runFanoutBudget?: RunFanoutBudgetSnapshot;
+	runFanoutRejection?: RunFanoutRejection;
+	activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: SubagentCapabilityAudit;
+	parallelHandoff?: ParallelHandoffReference;
+	lifecycleStatus?: {
+		processTerminal?: ProcessTerminalV1;
+	};
+	launchContractDigest?: string;
+	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+	/** Original launch contract whose persisted session is being revived. */
+	sourceLaunchContractDigest?: string;
+	/** Durable mission attached to this run, when mission mode was explicitly used. */
+	missionId?: string;
+	missionPath?: string;
+	/** Non-fatal automatic mission persistence failure. */
+	missionWarning?: string;
+	mission?: MissionRecord;
+	workflow?: {
+		value?: unknown;
+		trace: Array<{
+			operation: "run" | "status" | "steer";
+			key: string;
+			state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused" | "queued" | "delivered" | "missed";
+			agent?: string;
+			runId?: string;
+			phase?: string;
+			label?: string;
+			durationMs?: number;
+			error?: string;
+		}>;
+		emits: unknown[];
+		console: Array<{ level: "log" | "info" | "warn" | "error"; text: string }>;
+	};
+	chatProgress?: {
+		mode: "off" | "live-card";
+		repoRelation: "same" | "other";
+		repoLabel?: string;
+	};
+	missions?: {
+		records?: MissionRecord[];
+		globalEntries?: GlobalMissionIndexRecord[];
+		warnings: string[];
+	};
+	/** Project-scoped recurring schedule records and run history for management actions. */
+	schedules?: {
+		records?: unknown[];
+		runs?: unknown[];
+	};
+}
+
+// ============================================================================
+// Artifacts
+// ============================================================================
+
+export interface ArtifactPaths {
+	inputPath: string;
+	outputPath: string;
+	jsonlPath: string;
+	transcriptPath: string;
+	metadataPath: string;
+}
+
+export type ArtifactDirPreference = "project" | "session" | "temp";
+
+export interface ArtifactConfig {
+	enabled: boolean;
+	dir?: ArtifactDirPreference;
+	includeInput: boolean;
+	includeOutput: boolean;
+	includeJsonl: boolean;
+	includeTranscript?: boolean;
+	includeMetadata: boolean;
+	cleanupDays: number;
+}
+
+// ============================================================================
+// Async Execution
+// ============================================================================
+
+export interface AsyncParallelGroupStatus {
+	start: number;
+	count: number;
+	stepIndex: number;
+}
+
+export type NestedRunState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
+export type NestedOwnerState = "live" | "gone" | "unknown";
+
+export interface NestedRunAddress {
+	id: string;
+	parentRunId: string;
+	parentStepIndex?: number;
+	parentAgent?: string;
+	depth: number;
+	path: Array<{ runId: string; stepIndex?: number; agent?: string }>;
+}
+
+export interface NestedStepSummary {
+	agent: string;
+	status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
+	model?: string;
+	thinking?: string;
+	sessionFile?: string;
+	transcriptPath?: string;
+	transcriptError?: string;
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	startedAt?: number;
+	endedAt?: number;
+	error?: string;
+	watchdog?: ChildWatchdogProgress;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
+	processTerminal?: ProcessTerminalV1;
+	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: SubagentCapabilityAudit;
+	children?: NestedRunSummary[];
+}
+
+export interface NestedRunSummary extends NestedRunAddress {
+	asyncDir?: string;
+	pid?: number;
+	sessionId?: string;
+	sessionFile?: string;
+	intercomTarget?: string;
+	ownerIntercomTarget?: string;
+	leafIntercomTarget?: string;
+	ownerState?: NestedOwnerState;
+	controlInbox?: string;
+	capabilityToken?: string;
+	mode?: SubagentRunMode;
+	processTerminal?: ProcessTerminalV1;
+	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: SubagentCapabilityAudit;
+	state: NestedRunState;
+	agent?: string;
+	agents?: string[];
+	model?: string;
+	thinking?: string;
+	currentStep?: number;
+	chainStepCount?: number;
+	parallelGroups?: AsyncParallelGroupStatus[];
+	steps?: NestedStepSummary[];
+	children?: NestedRunSummary[];
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	totalTokens?: TokenUsage;
+	totalCost?: CostSummary;
+	startedAt?: number;
+	endedAt?: number;
+	lastUpdate?: number;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
+	error?: string;
+}
+
+export interface NestedRouteInfo {
+	rootRunId: string;
+	eventSink: string;
+	controlInbox: string;
+	capabilityToken: string;
+}
+
+export interface AsyncStartedEvent {
+	lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
+	id?: string;
+	asyncDir?: string;
+	/** Parent-resolved launch directory, used as a trusted artifact root while this session is live. */
+	cwd?: string;
+	/** Parent-resolved child session root, used only while this session owns the live run. */
+	sessionRoot?: string;
+	pid?: number;
+	sessionId?: string;
+	completionOwnerId?: string;
+	mode?: SubagentRunMode;
+	agent?: string;
+	agents?: string[];
+	/** Truncated first child task retained for backwards compatibility. */
+	task?: string;
+	/** Workflow-level caller task, falling back to the first child task. */
+	goal?: string;
+	chain?: string[];
+	chainStepCount?: number;
+	parallelGroups?: AsyncParallelGroupStatus[];
+	workflowGraph?: WorkflowGraphSnapshot;
+	launchContractDigest?: string;
+	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+	usageBudget?: UsageBudgetState;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	turnBudget?: TurnBudgetState;
+	nestedRoute?: NestedRouteInfo;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	parentWorkflowRunId?: string;
+	workflowKey?: string;
+}
+
+export type AgentRunnerConfig =
+	| { type: "pi" }
+	| {
+		type: "external-cli";
+		command: string;
+		args?: string[];
+		promptDelivery?: "stdin";
+	}
+	| {
+		type: "external-job";
+		provider: string;
+		options?: Record<string, unknown>;
+	};
+
+export interface ExternalCliRunnerStatus {
+	type: "external-cli";
+	command: string;
+	args: string[];
+	promptDelivery: "stdin";
+	capabilities: {
+		stop: true;
+		steer: false;
+		resume: false;
+		structuredOutput: false;
+		toolEvents: false;
+	};
+}
+
+export interface ExternalJobRunnerStatus {
+	type: "external-job";
+	provider: string;
+	options: Record<string, unknown>;
+	capabilities: {
+		stop: false;
+		steer: false;
+		resume: false;
+		structuredOutput: false;
+		toolEvents: false;
+	};
+}
+
+export interface ExternalJobStatus {
+	provider: string;
+	providerJobId?: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	handleUrl?: string;
+	conversationUrl?: string;
+	resultArtifactPath?: string;
+	state: "queued" | "running" | "completed" | "failed" | "stopped" | "blocked";
+	failureCode?: string;
+	failureMessage?: string;
+	blockingJobId?: string;
+	startedAt?: number;
+	updatedAt?: number;
+}
+
+export interface ExternalProcessStatus {
+	pid?: number;
+	startedAt: number;
+	endedAt?: number;
+	durationMs?: number;
+	exitCode?: number | null;
+	processSignal?: string | null;
+	stdoutPath: string;
+	stderrPath: string;
+}
+
+export interface AsyncStatus {
+	lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
+	runId: string;
+	/** Parent Pi process/window that owns local completion delivery. */
+	completionOwnerId?: string;
+	/** Host tool-call id retained when it differs from the internal run id. */
+	toolCallId?: string;
+	sessionId?: string;
+	mode: SubagentRunMode;
+	context?: "fresh" | "fork" | "mixed";
+	isNested?: boolean;
+	state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
+	/** Display-only dismissal marker for a reload-orphaned workflow. */
+	displayDismissedAt?: number;
+	error?: string;
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	steering?: SteeringStatus;
+	startedAt: number;
+	endedAt?: number;
+	lastUpdate?: number;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
+	usageBudget?: UsageBudgetState;
+	pid?: number;
+	cwd?: string;
+	/** Parent-resolved child session root retained for trusted restored transcript lookup. */
+	sessionRoot?: string;
+	currentStep?: number;
+	chainStepCount?: number;
+	pendingAppends?: number;
+	parallelGroups?: AsyncParallelGroupStatus[];
+	workflowGraph?: WorkflowGraphSnapshot;
+	processTerminal?: ProcessTerminalV1;
+	runFanoutBudget?: RunFanoutBudgetSnapshot;
+	runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
+	launchContractDigest?: string;
+	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: SubagentCapabilityAudit;
+	workflow?: Details["workflow"];
+	parentWorkflowRunId?: string;
+	workflowKey?: string;
+	/** Set when a durable schedule launched this run, so completions can name their origin. */
+	scheduleOrigin?: ScheduleOrigin;
+	steps?: Array<{
+		agent: string;
+		runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
+		externalProcess?: ExternalProcessStatus;
+		externalJob?: ExternalJobStatus;
+		/** Resolved launch context for this child step. */
+		context?: "fresh" | "fork";
+		/** Short caller-facing task/goal shown in fleet surfaces when available. */
+		description?: string;
+		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;
+		status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
+		children?: NestedRunSummary[];
+		sessionFile?: string;
+		transcriptPath?: string;
+		transcriptError?: string;
+		activityState?: ActivityState;
+		lastActivityAt?: number;
+		currentTool?: string;
+		currentToolArgs?: string;
+		currentToolStartedAt?: number;
+		currentPath?: string;
+		recentTools?: Array<{ tool: string; args: string; endMs: number }>;
+		recentOutput?: string[];
+		turnCount?: number;
+		toolCount?: number;
+		startedAt?: number;
+		endedAt?: number;
+		durationMs?: number;
+		exitCode?: number | null;
+		timedOut?: boolean;
+		stopped?: boolean;
+		turnBudget?: TurnBudgetState;
+		turnBudgetExceeded?: boolean;
+		wrapUpRequested?: boolean;
+		toolBudget?: ToolBudgetState;
+		toolBudgetBlocked?: boolean;
+		tokens?: TokenUsage;
+		skills?: string[];
+		model?: string;
+		thinking?: string;
+		attemptedModels?: string[];
+		modelAttempts?: ModelAttempt[];
+		totalCost?: CostSummary;
+		steering?: SteeringStatus;
+		error?: string;
+		structuredOutput?: unknown;
+		structuredOutputPath?: string;
+		structuredOutputSchemaPath?: string;
+		acceptance?: AcceptanceLedger;
+		agentContract?: AgentContract;
+		launchContractDigest?: string;
+		launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+		runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+		execution?: ExecutionProjection;
+		review?: ReviewProjection;
+		effects?: EffectsProjection;
+		watchdog?: ChildWatchdogProgress;
+		processTerminal?: ProcessTerminalV1;
+		capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+		capabilityAudit?: SubagentCapabilityAudit;
+	}>;
+	sessionDir?: string;
+	outputFile?: string;
+	totalTokens?: TokenUsage;
+	totalCost?: CostSummary;
+	sessionFile?: string;
+	outputs?: ChainOutputMap;
+	parallelHandoff?: ParallelHandoffReference;
+}
+
+export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & {
+	index?: number;
+	description?: string;
+};
+
+export interface AsyncJobState {
+	asyncId: string;
+	asyncDir: string;
+	/** Host tool-call id retained when it differs from the internal run id. */
+	toolCallId?: string;
+	/** Parent-resolved launch directory retained for trusted live artifact lookup. */
+	cwd?: string;
+	/** Parent-resolved child session root retained for trusted live transcript lookup. */
+	sessionRoot?: string;
+	status: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
+	/** Short caller-facing task/goal shown in fleet surfaces when available. */
+	description?: string;
+	pid?: number;
+	sessionId?: string;
+	completionOwnerId?: string;
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	steering?: SteeringStatus;
+	mode?: SubagentRunMode;
+	/** Run-level context summary derived from step contexts. */
+	context?: "fresh" | "fork" | "mixed";
+	agents?: string[];
+	currentStep?: number;
+	chainStepCount?: number;
+	parallelGroups?: AsyncParallelGroupStatus[];
+	steps?: AsyncJobStep[];
+	stepsTotal?: number;
+	runningSteps?: number;
+	completedSteps?: number;
+	hasParallelGroups?: boolean;
+	activeParallelGroup?: boolean;
+	startedAt?: number;
+	updatedAt?: number;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudget?: TurnBudgetState;
+	turnBudgetExceeded?: boolean;
+	wrapUpRequested?: boolean;
+	toolBudget?: ToolBudgetState;
+	toolBudgetBlocked?: boolean;
+	sessionDir?: string;
+	outputFile?: string;
+	totalTokens?: TokenUsage;
+	totalCost?: CostSummary;
+	usageBudget?: UsageBudgetState;
+	sessionFile?: string;
+	controlEventCursor?: number;
+	nestedRoute?: NestedRouteInfo;
+	nestedChildren?: NestedRunSummary[];
+	parentWorkflowRunId?: string;
+	workflowKey?: string;
+	workflow?: Details["workflow"];
+}
+
+export interface ForegroundResumeChild {
+	agent: string;
+	index: number;
+	context?: "fresh" | "fork";
+	sessionFile?: string;
+	model?: string;
+	thinking?: string;
+	status: SubagentResultStatus;
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	tokens?: number;
+	toolCount?: number;
+	exitCode?: number;
+	error?: string;
+	finalOutput?: string;
+	outputState?: SubagentOutputState;
+	outputMode?: OutputMode;
+	savedOutputPath?: string;
+	outputSaveError?: string;
+	artifactPaths?: ArtifactPaths;
+	transcriptPath?: string;
+	transcriptError?: string;
+	detachedReason?: string;
+	acceptance?: AcceptanceLedger;
+	agentContract?: AgentContract;
+	launchContractDigest?: string;
+	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
+	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
+	execution?: ExecutionProjection;
+	review?: ReviewProjection;
+	effects?: EffectsProjection;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: SubagentCapabilityAudit;
+	updatedAt?: number;
+}
+
+export interface ForegroundResumeRun {
+	runId: string;
+	mode: SubagentRunMode;
+	cwd: string;
+	/** Originating parent session. Detached exits can outlive the active session. */
+	sessionId?: string;
+	updatedAt: number;
+	children: ForegroundResumeChild[];
+}
+
+export interface ForegroundChildControl {
+	index: number;
+	agent: string;
+	description?: string;
+	startedAt: number;
+	updatedAt: number;
+	currentActivityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	tokens?: number;
+	inputTokens?: number;
+	outputTokens?: number;
+	model?: string;
+	thinking?: string;
+	toolCount?: number;
+	interrupt?: () => boolean;
+	detach?: () => boolean;
+}
+
+export interface ForegroundRunControl {
+	runId: string;
+	/** Workflow shell that owns this live foreground child, when applicable. */
+	parentWorkflowRunId?: string;
+	/** Stable workflow lane key for this live foreground child. */
+	workflowKey?: string;
+	/** Private control root used to steer a live workflow-owned child. */
+	workflowSteeringDir?: string;
+	/** Originating parent session; required for public fleet projection. */
+	sessionId?: string;
+	mode: SubagentRunMode;
+	startedAt: number;
+	updatedAt: number;
+	/** Effective working directory used to resolve live transcript artifacts. */
+	cwd?: string;
+	currentAgent?: string;
+	currentIndex?: number;
+	/** Short caller-facing task/goal shown in fleet surfaces when available. */
+	description?: string;
+	currentActivityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	tokens?: number;
+	inputTokens?: number;
+	outputTokens?: number;
+	model?: string;
+	thinking?: string;
+	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;
+	nestedChildren?: NestedRunSummary[];
+	interrupt?: () => boolean;
+	detach?: () => boolean;
+}
+
+export interface WaitSubscriptionRecord {
+	/** v1 is read-only migration input; old runtimes reject v2 rather than replay it. */
+	version: 1 | 2;
+	token: string;
+	sessionId: string;
+	targetKind: "async" | "foreground";
+	runId: string;
+	requestedId: string;
+	createdAt: number;
+	expiresAt: number;
+	lastAttentionKey?: string;
+	controlKey?: string;
+	seenControlKeys?: string[];
+	delivery?: {
+		attemptId: string;
+		outcome: string;
+		state: "unknown" | "accepted";
+		attemptedAt: number;
+	};
+}
+
+export interface ActiveAsyncCapacitySnapshot {
+	used: number;
+	/** Zero means the opt-in cap is disabled. */
+	limit: number;
+}
+
+export interface SubagentState {
+	baseCwd: string;
+	currentSessionId: string | null;
+	/** Reload-stable identity for this parent Pi process/window. */
+	completionOwnerId?: string;
+	/** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
+	artifactDirPreference?: ArtifactDirPreference;
+	/** Runtime authority snapshot used by optional inspector controls. */
+	authorityPolicy?: AuthorityPolicyConfig;
+	/** Runtime mission-store snapshot used by optional inspector context. */
+	missionStoreConfig?: MissionStoreConfig;
+	parentSessionFile?: string | null;
+	/** Extension-owned roots trusted for child session transcript reads. */
+	trustedSessionRoots?: string[];
+	/** Live async session roots created by this parent executor, keyed by run id. */
+	liveAsyncSessionRoots?: Map<string, string>;
+	/** Last valid parent session model observed for this session; used when continuation contexts omit ctx.model. */
+	lastParentModel?: { provider: string; id: string };
+	subagentInProgress?: boolean;
+	subagentSpawns?: {
+		sessionId: string | null;
+		count: number;
+		configuredLimit?: number | null;
+		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>;
+	/** Suppress dynamic status widgets while the fleet overlay owns the viewport. */
+	fleetInspectorOpen?: boolean;
+	/** Temporarily suppress dynamic widgets while Pi compacts the session. */
+	widgetsSuspended?: boolean;
+	foregroundRuns?: Map<string, ForegroundResumeRun>;
+	foregroundControls: Map<string, ForegroundRunControl>;
+	lastForegroundControlId: string | null;
+	cleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
+	lastUiContext: ExtensionContext | null;
+	poller: NodeJS.Timeout | null;
+	completionSeen: Map<string, number>;
+	/** Terminal result payloads observed by the result watcher, keyed by run id and pruned by the completion TTL. */
+	completedResults?: Map<string, { seenAt: number; completion: WaitCompletion }>;
+	watcher: FSWatcher | null;
+	watcherRestartTimer: ReturnType<typeof setTimeout> | null;
+	resultFileCoalescer: {
+		schedule(file: string, delayMs?: number): boolean;
+		clear(): void;
+	};
+	/** Current-session durable non-blocking wait registrations. */
+	waitSubscriptions?: Map<string, WaitSubscriptionRecord>;
+	/** Live in-process workflow controllers. Durable status remains on disk after settlement. */
+	workflowControllers?: Map<string, AbortController>;
+}
+
+// ============================================================================
+// Display
+// ============================================================================
+
+export type DisplayItem = 
+	| { type: "text"; text: string } 
+	| { type: "tool"; name: string; args: Record<string, unknown> };
+
+// ============================================================================
+// Error Handling
+// ============================================================================
+
+export interface ErrorInfo {
+	hasError: boolean;
+	exitCode?: number;
+	errorType?: string;
+	details?: string;
+}
+
+export interface IntercomEventBus {
+	on(channel: string, handler: (data: unknown) => void): () => void;
+	emit(channel: string, data: unknown): void;
+}
+
+export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
+export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
+export const SUBAGENT_ASYNC_STARTED_EVENT = "subagent:async-started";
+export const SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
+export const SUBAGENT_PROCESS_TERMINAL_EVENT = "subagent:process-terminal";
+export const SUBAGENT_FOREGROUND_COMPLETE_EVENT = "subagent:foreground-complete";
+export const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
+export const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
+export const SUBAGENT_STEERING_NOTICE_EVENT = "subagent:steering-notice";
+export const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
+export const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
+
+// ============================================================================
+// Execution Options
+// ============================================================================
+
+export interface RunSyncOptions {
+	/** Opt-in global permission rules; missing tools remain allowed. */
+	permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
+	/** Session id of the direct parent session for permission-system ask forwarding. */
+	parentSessionId?: string;
+	/** Private prompt-runtime steering transport for workflow-owned foreground children. */
+	steerInboxDir?: string;
+	steerCapabilityPath?: string;
+	steerAckDir?: string;
+	/** Resolved launch context for this child. */
+	context?: "fresh" | "fork";
+	cwd?: string;
+	signal?: AbortSignal;
+	interruptSignal?: AbortSignal;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	/** Per-call per-tool timeout (ms), resolved with the agent/config/environment ladder at execution. */
+	toolTimeoutMs?: number;
+	/** Raw global config.toolTimeoutMs, used by the per-child resolver. */
+	configToolTimeoutMs?: number;
+	turnBudget?: ResolvedTurnBudget;
+	usageBudget?: UsageBudgetConfig;
+	/** Enforce maxTurns + graceTurns as a hard model-turn boundary. */
+	enforceHardTurnLimit?: boolean;
+	toolBudget?: ResolvedToolBudget;
+	allowZeroToolBudget?: boolean;
+	allowIntercomDetach?: boolean;
+	intercomEvents?: IntercomEventBus;
+	onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
+	onControlEvent?: (event: ControlEvent) => void;
+	/** Exposes a non-terminating detach callback while the child is active. */
+	onDetachReady?: (detach: (reason?: string) => boolean) => void;
+	/** Internal foreground receipt proposal; returns true only when the outer waiter accepted it. */
+	onDetachReceipt?: (result: SingleResult) => boolean;
+	/** Authoritative terminal result, emitted only after the full detached run finalizes. */
+	onDetachedExit?: (result: SingleResult) => void;
+	controlConfig?: ResolvedControlConfig;
+	intercomSessionName?: string;
+	orchestratorIntercomTarget?: string;
+	maxOutput?: MaxOutputConfig;
+	artifactsDir?: string;
+	artifactConfig?: ArtifactConfig;
+	runId: string;
+	index?: number;
+	sessionDir?: string;
+	sessionFile?: string;
+	share?: boolean;
+	outputPath?: string;
+	outputMode?: OutputMode;
+	maxSubagentDepth?: number;
+	/** 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;
+	/** The override came from the running parent session, not configuration. */
+	modelOverrideFromParent?: boolean;
+	/** 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 */
+	availableModels?: Array<{ provider: string; id: string; fullId: string }>;
+	/** Current parent-session provider to prefer for ambiguous bare model ids */
+	preferredModelProvider?: string;
+	/** Optional subagent model-scope enforcement for fallback candidates */
+	modelScope?: ModelScopeConfig;
+	/** Skills to make available (overrides agent default if provided) */
+	skills?: string[];
+	structuredOutput?: {
+		schema: JsonSchemaObject;
+		schemaPath: string;
+		outputPath: string;
+	};
+	agentContract?: AgentContract;
+	acceptance?: AcceptanceInput;
+	acceptanceContext?: {
+		mode?: SubagentRunMode;
+		async?: boolean;
+		dynamic?: boolean;
+		dynamicGroup?: boolean;
+	};
+	/** Private live callback for the exact child prompt after runtime acceptance injection. */
+	onEffectivePrompt?: (prompt: string) => void;
+	/** Internal lifecycle hook for the observer shared across retries of one logical child. */
+	onOrcaProgressTabCreated?: (tab: import("../runs/shared/orca-progress-tabs.ts").OrcaProgressTab) => void;
+}
+
+export type IntercomBridgeMode = "off" | "fork-only" | "always";
+
+export interface IntercomBridgeConfig {
+	mode?: IntercomBridgeMode;
+	instructionFile?: string;
+	/** Deliver grouped completion messages through an external acknowledged intercom listener. */
+	resultDelivery?: boolean;
+}
+
+interface TopLevelParallelConfig {
+	maxTasks?: number;
+	concurrency?: number;
+}
+
+interface ExtensionChainConfig {
+	dynamicFanout?: {
+		maxItems?: number;
+	};
+}
+
+export interface ProactiveSkillSubagentsConfig {
+	enabled?: boolean;
+	minReferences?: number;
+	maxRecommendations?: number;
+	preferredAgent?: string;
+}
+
+export type ToolDescriptionMode = "full" | "compact" | "custom";
+export type InlineToolDisplay = "rich" | "summary";
+
+export interface ScheduledRunsConfig {
+	enabled?: boolean;
+	maxPending?: number;
+	/** Absolute or `~/` root for per-project durable schedules. */
+	storeRoot?: string;
+}
+
+export type FleetViewPlacement = "aboveEditor" | "belowEditor";
+
+export const FLEET_KEYBINDING_ACTIONS = [
+	"close",
+	"scrollUp",
+	"scrollDown",
+	"selectUp",
+	"selectDown",
+	"selectFirst",
+	"selectLast",
+	"pageUp",
+	"pageDown",
+	"refresh",
+	"steer",
+	"inspect",
+	"stop",
+	"toggleTools",
+] as const;
+
+export type FleetKeybindingAction = typeof FLEET_KEYBINDING_ACTIONS[number];
+export type FleetKeybindingsConfig = Partial<Record<FleetKeybindingAction, string[]>>;
+
+export interface OrcaProgressTabsConfig {
+	/** Create one Orca terminal tab per running subagent. Experimental and opt-in. */
+	enabled?: boolean;
+}
+
+export interface MainWindowRendererConfig {
+	/** Unit of horizontal space in main chat subagent call/result rows. Omit to preserve current spacing. Set 0 for no extra padding. */
+	horizontalSpacing?: number;
+	/** Maximum collapsed rich-result rows. Expanded output is not capped. */
+	compactResultMaxLines?: number;
+}
+
+export interface ExtensionConfig {
+	asyncByDefault?: boolean;
+	/** Set the context for launches that omit an explicit context. */
+	defaultSubagentContext?: "fresh" | "fork";
+	/** Optional shortcut that detaches the active foreground single-subagent run. */
+	foregroundDetachShortcut?: string;
+	/** Show the Claude Code-style navigable fleet. Defaults to true. */
+	fleetView?: boolean;
+	/** Place the persistent FleetView above or below the editor. Defaults to belowEditor. */
+	fleetViewPlacement?: FleetViewPlacement;
+	/** Local keybindings for the full Fleet inspector. */
+	fleetKeybindings?: FleetKeybindingsConfig;
+	/** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
+	asyncWidget?: boolean;
+	/** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
+	toolDescriptionMode?: ToolDescriptionMode;
+	/** Inline chat rendering for the subagent tool. Defaults to rich. */
+	inlineToolDisplay?: InlineToolDisplay;
+	/** Density controls for the main chat subagent call/result renderer. */
+	mainWindowRenderer?: MainWindowRendererConfig;
+	/** Experimental observer: mirror each native subagent's progress into a new Orca tab. */
+	orcaProgressTabs?: OrcaProgressTabsConfig;
+	forceTopLevelAsync?: boolean;
+	waitTool?: WaitToolConfig;
+	defaultSessionDir?: string;
+	singleRunOutputBaseDir?: string;
+	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;
+	/**
+	 * Optional hard per-tool-call timeout in milliseconds. Bounds a single
+	 * subagent tool call inside the child; the run-level timeout remains
+	 * authoritative. Known-fast built-in tools have a five-minute default when
+	 * this is undefined. Precedence: call param > agent frontmatter > this config >
+	 * PI_SUBAGENT_TOOL_TIMEOUT_MS. Must be a positive integer; invalid values
+	 * are rejected with an error.
+	 */
+	toolTimeoutMs?: number;
+	control?: ControlConfig;
+	completionBatch?: CompletionBatchConfig;
+	turnBudget?: TurnBudgetConfig;
+	toolBudget?: ToolBudgetConfig;
+	/** Opt-in native tool permissions. Bash remains outside this policy. */
+	permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
+	usageBudget?: UsageBudgetConfig;
+	parallel?: TopLevelParallelConfig;
+	chain?: ExtensionChainConfig;
+	worktreeSetupHook?: string;
+	worktreeSetupHookTimeoutMs?: number;
+	worktreeBaseDir?: string;
+	/** Where to store subagent artifact files. Defaults to "session" (the pi session directory, or OS temp when unavailable). Set to "project" for cwd/.pi/subagents. */
+	artifactDir?: ArtifactDirPreference;
+	/** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
+	artifactConfig?: Pick<ArtifactConfig, "cleanupDays">;
+	intercomBridge?: IntercomBridgeConfig;
+	proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
+	scheduledRuns?: ScheduledRunsConfig;
+	/** Durable mission behavior. Missions are automatic by default; set enabled:false to disable auto-create. Explicit mission actions/fields still work. */
+	missions?: MissionStoreConfig;
+	/** Small fixed authority policy for the supported operational actions. */
+	authorityPolicy?: AuthorityPolicyConfig;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
+	bytes: 200 * 1024,
+	lines: 5000,
+};
+
+export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
+	enabled: true,
+	dir: "session",
+	includeInput: true,
+	includeOutput: true,
+	includeJsonl: false,
+	includeTranscript: true,
+	includeMetadata: true,
+	cleanupDays: 7,
+};
+
+function sanitizeTempScopeSegment(value: string): string {
+	const sanitized = value
+		.trim()
+		.replace(/[^A-Za-z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return sanitized || "unknown";
+}
+
+export function resolveTempScopeId(options?: {
+	env?: NodeJS.ProcessEnv;
+	getuid?: (() => number) | undefined;
+	userInfo?: (() => { username?: string | null }) | undefined;
+	homedir?: (() => string) | undefined;
+}): string {
+	const env = options?.env ?? process.env;
+	const getuid = options && Object.hasOwn(options, "getuid")
+		? options.getuid
+		: process.getuid?.bind(process);
+	if (typeof getuid === "function") {
+		return `uid-${getuid()}`;
+	}
+
+	for (const key of ["USERNAME", "USER", "LOGNAME"] as const) {
+		const value = env[key];
+		if (value) return `user-${sanitizeTempScopeSegment(value)}`;
+	}
+
+	const userInfo = options && Object.hasOwn(options, "userInfo")
+		? options.userInfo
+		: os.userInfo;
+	try {
+		const username = userInfo?.().username;
+		if (username) return `user-${sanitizeTempScopeSegment(username)}`;
+	} catch {
+		// Fall through to home-directory-based scoping.
+	}
+
+	const homedir = env.USERPROFILE ?? env.HOME;
+	if (homedir) return `home-${sanitizeTempScopeSegment(homedir)}`;
+
+	const resolveHomedir = options && Object.hasOwn(options, "homedir")
+		? options.homedir
+		: os.homedir;
+	try {
+		const fallbackHomedir = resolveHomedir?.();
+		if (fallbackHomedir) return `home-${sanitizeTempScopeSegment(fallbackHomedir)}`;
+	} catch {
+		// Fall through to the last-resort shared scope.
+	}
+
+	return "shared";
+}
+
+const MAX_PARALLEL = 8;
+export const MAX_CONCURRENCY = 4;
+const configuredTempRoot = process.env.PI_SUBAGENTS_TEMP_ROOT?.trim();
+export const TEMP_ROOT_DIR = configuredTempRoot
+	? path.resolve(configuredTempRoot)
+	: path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
+export const RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
+export const ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
+export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
+export const TEMP_ARTIFACTS_DIR = path.join(TEMP_ROOT_DIR, "artifacts");
+
+export const DIRS = {
+	results: RESULTS_DIR,
+	async: ASYNC_DIR,
+	chain: CHAIN_RUNS_DIR,
+	artifacts: TEMP_ARTIFACTS_DIR,
+};
+export const WIDGET_KEY = "subagent-async";
+export const SLASH_RESULT_TYPE = "subagent-slash-result";
+export const SLASH_TEXT_RESULT_TYPE = "subagent-slash-text-result";
+export const SLASH_SUBAGENT_REQUEST_EVENT = "subagent:slash:request";
+export const SLASH_SUBAGENT_STARTED_EVENT = "subagent:slash:started";
+export const SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";
+export const SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
+export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
+export const POLL_INTERVAL_MS = 250;
+export const MAX_WIDGET_JOBS = 4;
+export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
+export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
+
+export const DEFAULT_FORK_PREAMBLE =
+	"You are a delegated subagent running from a fork of the parent session. " +
+	"Treat the inherited conversation as reference-only context, not a live thread to continue. " +
+	"Do not continue or answer prior messages as if they are waiting for a reply. " +
+	"Your sole job is to execute the task below and return a focused result for that task using your tools.";
+
+function normalizeTopLevelParallelValue(value: unknown): number | undefined {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	if (!Number.isInteger(parsed) || parsed < 1) return undefined;
+	return parsed;
+}
+
+export function resolveTopLevelParallelMaxTasks(value: unknown): number {
+	return normalizeTopLevelParallelValue(value) ?? MAX_PARALLEL;
+}
+
+export function resolveTopLevelParallelConcurrency(
+	override: unknown,
+	configValue: unknown,
+): number {
+	return normalizeTopLevelParallelValue(override)
+		?? normalizeTopLevelParallelValue(configValue)
+		?? MAX_CONCURRENCY;
+}
+
+export function getAsyncConfigPath(suffix: string): string {
+	return path.join(TEMP_ROOT_DIR, `async-cfg-${suffix}.json`);
+}
+
+export function wrapForkTask(task: string, preamble?: string | false): string {
+	if (preamble === false) return task;
+	const effectivePreamble = preamble ?? DEFAULT_FORK_PREAMBLE;
+	const wrappedPrefix = `${effectivePreamble}\n\nTask:\n`;
+	if (task.startsWith(wrappedPrefix)) return task;
+	return `${wrappedPrefix}${task}`;
+}
+
+// ============================================================================
+// Recursion Depth Guard
+// ============================================================================
+
+function normalizeNonNegativeInteger(value: unknown): number | undefined {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	if (!Number.isInteger(parsed) || parsed < 0) return undefined;
+	return parsed;
+}
+
+export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
+	return normalizeNonNegativeInteger(value);
+}
+
+export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
+	return normalizeMaxSubagentDepth(process.env.PI_SUBAGENT_MAX_DEPTH)
+		?? normalizeMaxSubagentDepth(configMaxDepth)
+		?? DEFAULT_SUBAGENT_MAX_DEPTH;
+}
+
+export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDepth?: number): number {
+	const normalizedParent = normalizeMaxSubagentDepth(parentMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
+	const normalizedAgent = normalizeMaxSubagentDepth(agentMaxDepth);
+	return normalizedAgent === undefined ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
+}
+
+export function checkSubagentDepth(configMaxDepth?: number): { blocked: boolean; depth: number; maxDepth: number } {
+	const depth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
+	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
+	const blocked = Number.isFinite(depth) && depth >= maxDepth;
+	return { blocked, depth, maxDepth };
+}
+
+export function getSubagentDepthEnv(maxDepth?: number): Record<string, string> {
+	const parentDepth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
+	const nextDepth = Number.isFinite(parentDepth) ? parentDepth + 1 : 1;
+	return {
+		PI_SUBAGENT_DEPTH: String(nextDepth),
+		PI_SUBAGENT_MAX_DEPTH: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
+	};
+}
+
+export function normalizeMaxSubagentSpawnsPerSession(value: unknown): number | undefined {
+	return normalizeNonNegativeInteger(value);
+}
+
+export function resolveMaxSubagentSpawnsPerSession(configMaxSpawns?: number): number | undefined {
+	const envMaxSpawns = normalizeMaxSubagentSpawnsPerSession(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_SESSION);
+	if (envMaxSpawns !== undefined) return envMaxSpawns === 0 ? undefined : envMaxSpawns;
+	const configuredMaxSpawns = normalizeMaxSubagentSpawnsPerSession(configMaxSpawns);
+	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
+// ============================================================================
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+export function truncateOutput(
+	output: string,
+	config: Required<MaxOutputConfig>,
+	artifactPath?: string,
+): TruncationResult {
+	const lines = output.split("\n");
+	const bytes = Buffer.byteLength(output, "utf-8");
+
+	if (bytes <= config.bytes && lines.length <= config.lines) {
+		return { text: output, truncated: false };
+	}
+
+	let truncatedLines = lines;
+	if (lines.length > config.lines) {
+		truncatedLines = lines.slice(0, config.lines);
+	}
+
+	let result = truncatedLines.join("\n");
+	if (Buffer.byteLength(result, "utf-8") > config.bytes) {
+		let low = 0;
+		let high = result.length;
+		while (low < high) {
+			const mid = Math.floor((low + high + 1) / 2);
+			if (Buffer.byteLength(result.slice(0, mid), "utf-8") <= config.bytes) {
+				low = mid;
+			} else {
+				high = mid - 1;
+			}
+		}
+		result = result.slice(0, low);
+	}
+
+	const keptLines = result.split("\n").length;
+	const marker = `[TRUNCATED: showing first ${keptLines} of ${lines.length} lines, ${formatBytes(Buffer.byteLength(result))} of ${formatBytes(bytes)}${artifactPath ? ` - full output at ${artifactPath}` : ""}]\n`;
+
+	return {
+		text: marker + result,
+		truncated: true,
+		originalBytes: bytes,
+		originalLines: lines.length,
+		artifactPath,
+	};
+}