pi-subagents 0.31.0 → 0.32.0

package/src/shared/fork-context.ts

@@ -1,27 +1,115 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 
 type SubagentExecutionContext = "fresh" | "fork";
 
+interface BranchSessionEntry {
+	type: string;
+	id?: string;
+	parentId?: string | null;
+	timestamp?: string;
+	message?: {
+		role?: string;
+		content?: unknown;
+		provider?: string;
+		api?: string;
+		model?: string;
+	};
+	thinkingLevel?: string;
+}
+
+interface BranchSessionManager {
+	createBranchedSession(leafId: string): string | undefined;
+	getHeader?: () => BranchSessionEntry | null;
+	getEntries?: () => BranchSessionEntry[];
+}
+
 interface ForkableSessionManager {
 	getSessionFile(): string | undefined;
 	getLeafId(): string | null;
 	getSessionDir?(): string;
-	openSession?: (path: string, sessionDir?: string) => { createBranchedSession(leafId: string): string | undefined };
+	openSession?: (path: string, sessionDir?: string) => BranchSessionManager;
 }
 
 interface ForkContextResolverOptions {
-	openSession?: (path: string, sessionDir?: string) => { createBranchedSession(leafId: string): string | undefined };
+	openSession?: (path: string, sessionDir?: string) => BranchSessionManager;
+}
+
+interface ForkContextResolution {
+	sessionFile: string;
+	thinkingOverride?: "off";
 }
 
 interface ForkContextResolver {
 	sessionFileForIndex(index?: number): string | undefined;
+	thinkingOverrideForIndex(index?: number): "off" | undefined;
 }
 
 export function resolveSubagentContext(value: unknown): SubagentExecutionContext {
 	return value === "fork" ? "fork" : "fresh";
 }
 
+function isUnsafeAnthropicThinkingBlock(message: BranchSessionEntry["message"], block: unknown): boolean {
+	if (!message || !block || typeof block !== "object" || !("type" in block)) return false;
+	const provider = typeof message.provider === "string" ? message.provider.toLowerCase() : "";
+	const api = typeof message.api === "string" ? message.api.toLowerCase() : "";
+	const model = typeof message.model === "string" ? message.model.toLowerCase() : "";
+	const isAnthropic = provider === "anthropic" || api === "anthropic-messages" || model.startsWith("anthropic/");
+	if (block.type === "redacted_thinking") return true;
+	if (block.type !== "thinking" || !isAnthropic) return false;
+	const signature = "thinkingSignature" in block ? block.thinkingSignature : "signature" in block ? block.signature : undefined;
+	return block.redacted === true || (typeof signature === "string" && signature.length > 0);
+}
+
+function createEntryId(entries: BranchSessionEntry[]): string {
+	const ids = new Set(entries.map((entry) => entry.id).filter((id): id is string => typeof id === "string"));
+	for (let attempt = 0; attempt < 100; attempt++) {
+		const id = randomUUID().slice(0, 8);
+		if (!ids.has(id)) return id;
+	}
+	return randomUUID();
+}
+
+function appendThinkingOffEntry(entries: BranchSessionEntry[]): void {
+	const last = entries[entries.length - 1];
+	if (last?.type === "thinking_level_change" && last.thinkingLevel === "off") return;
+	const parent = [...entries].reverse().find((entry) => typeof entry.id === "string");
+	entries.push({
+		type: "thinking_level_change",
+		id: createEntryId(entries),
+		parentId: parent?.id ?? null,
+		timestamp: new Date().toISOString(),
+		thinkingLevel: "off",
+	});
+}
+
+function sanitizeUnsafeThinkingBlocks(entries: BranchSessionEntry[]): boolean {
+	let sanitized = false;
+	for (const entry of entries) {
+		if (entry.type !== "message" || entry.message?.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
+		const filtered = entry.message.content.filter((block) => !isUnsafeAnthropicThinkingBlock(entry.message, block));
+		if (filtered.length === entry.message.content.length) continue;
+		entry.message.content = filtered;
+		sanitized = true;
+	}
+	if (sanitized) appendThinkingOffEntry(entries);
+	return sanitized;
+}
+
+function readSessionEntries(sessionFile: string): BranchSessionEntry[] {
+	const lines = fs.readFileSync(sessionFile, "utf-8").split("\n").filter((line) => line.trim().length > 0);
+	return lines.map((line, index) => {
+		try {
+			return JSON.parse(line) as BranchSessionEntry;
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			throw new Error(`Unable to inspect forked session ${sessionFile}: invalid JSONL on line ${index + 1}: ${cause.message}`, { cause });
+		}
+	});
+}
+
 export function createForkContextResolver(
 	sessionManager: ForkableSessionManager,
 	requestedContext: unknown,
@@ -30,6 +118,7 @@ export function createForkContextResolver(
 	if (resolveSubagentContext(requestedContext) !== "fork") {
 		return {
 			sessionFileForIndex: () => undefined,
+			thinkingOverrideForIndex: () => undefined,
 		};
 	}
 
@@ -47,30 +136,52 @@ export function createForkContextResolver(
 		?? sessionManager.openSession
 		?? ((file: string, dir?: string) => SessionManager.open(file, dir));
 	const sessionDir = sessionManager.getSessionDir?.();
-	const cachedSessionFiles = new Map<number, string>();
+	const cachedResolutions = new Map<number, ForkContextResolution>();
 
-	return {
-		sessionFileForIndex(index = 0): string | undefined {
-			const cached = cachedSessionFiles.get(index);
-			if (cached) return cached;
-			try {
-				if (!fs.existsSync(parentSessionFile)) {
-					throw new Error(`Parent session file does not exist: ${parentSessionFile}. Pi has not persisted enough history to fork yet.`);
-				}
-				const sourceManager = openSession(parentSessionFile, sessionDir);
-				const sessionFile = sourceManager.createBranchedSession(leafId);
-				if (!sessionFile) {
-					throw new Error("Session manager did not return a forked session file.");
+	const resolveFork = (index = 0): ForkContextResolution => {
+		const cached = cachedResolutions.get(index);
+		if (cached) return cached;
+		try {
+			if (!fs.existsSync(parentSessionFile)) {
+				throw new Error(`Parent session file does not exist: ${parentSessionFile}. Pi has not persisted enough history to fork yet.`);
+			}
+			const sourceManager = openSession(parentSessionFile, sessionDir);
+			const sessionFile = sourceManager.createBranchedSession(leafId);
+			if (!sessionFile) {
+				throw new Error("Session manager did not return a forked session file.");
+			}
+			let thinkingOverride: "off" | undefined;
+			if (!fs.existsSync(sessionFile)) {
+				const header = sourceManager.getHeader?.();
+				const entries = sourceManager.getEntries?.();
+				if (!header || !entries) {
+					throw new Error(`Session manager returned a forked session file that does not exist and cannot be persisted by fallback: ${sessionFile}`);
 				}
-				if (!fs.existsSync(sessionFile)) {
-					throw new Error(`Session manager returned a forked session file that does not exist: ${sessionFile}`);
+				if (sanitizeUnsafeThinkingBlocks(entries)) thinkingOverride = "off";
+				fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
+				fs.writeFileSync(sessionFile, `${[header, ...entries].map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
+			} else {
+				const entries = readSessionEntries(sessionFile);
+				if (sanitizeUnsafeThinkingBlocks(entries)) {
+					thinkingOverride = "off";
+					fs.writeFileSync(sessionFile, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
 				}
-				cachedSessionFiles.set(index, sessionFile);
-				return sessionFile;
-			} catch (error) {
-				const cause = error instanceof Error ? error : new Error(String(error));
-				throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });
 			}
+			const resolution = { sessionFile, ...(thinkingOverride ? { thinkingOverride } : {}) };
+			cachedResolutions.set(index, resolution);
+			return resolution;
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });
+		}
+	};
+
+	return {
+		sessionFileForIndex(index = 0): string | undefined {
+			return resolveFork(index).sessionFile;
+		},
+		thinkingOverrideForIndex(index = 0): "off" | undefined {
+			return resolveFork(index).thinkingOverride;
 		},
 	};
 }

package/src/shared/types.ts

@@ -144,17 +144,25 @@ export interface ControlEvent {
 
 export type SubagentResultStatus = "completed" | "failed" | "paused" | "detached";
 export type SubagentRunMode = "single" | "parallel" | "chain";
+export const SUBAGENT_LIFECYCLE_ARTIFACT_VERSION = 1;
+export type SubagentLifecycleArtifactVersion = typeof SUBAGENT_LIFECYCLE_ARTIFACT_VERSION;
 
 export type PublicNestedStepSummary = Pick<
 	NestedStepSummary,
-	"agent" | "status" | "sessionFile" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "startedAt" | "endedAt" | "error"
+	"agent" | "status" | "sessionFile" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "startedAt" | "endedAt" | "error" | "timedOut"
 > & {
 	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" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "totalTokens" | "startedAt" | "endedAt" | "lastUpdate" | "error"
+	"id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "totalTokens" | "totalCost" | "startedAt" | "endedAt" | "lastUpdate" | "error" | "timeoutMs" | "deadlineAt" | "timedOut"
 > & {
 	steps?: PublicNestedStepSummary[];
 	children?: PublicNestedRunSummary[];
@@ -416,6 +424,7 @@ export interface SingleResult {
 	structuredOutputPath?: string;
 	structuredOutputSchemaPath?: string;
 	acceptance?: AcceptanceLedger;
+	children?: NestedRunSummary[];
 }
 
 export interface Details {
@@ -426,6 +435,9 @@ export interface Details {
 	controlEvents?: ControlEvent[];
 	asyncId?: string;
 	asyncDir?: string;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
 	progress?: AgentProgress[];
 	progressSummary?: ProgressSummary;
 	artifacts?: {
@@ -444,6 +456,10 @@ export interface Details {
 	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;
 }
 
 // ============================================================================
@@ -502,6 +518,7 @@ export interface NestedStepSummary {
 	startedAt?: number;
 	endedAt?: number;
 	error?: string;
+	timedOut?: boolean;
 	children?: NestedRunSummary[];
 }
 
@@ -533,9 +550,13 @@ export interface NestedRunSummary extends NestedRunAddress {
 	turnCount?: number;
 	toolCount?: number;
 	totalTokens?: TokenUsage;
+	totalCost?: CostSummary;
 	startedAt?: number;
 	endedAt?: number;
 	lastUpdate?: number;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
 	error?: string;
 }
 
@@ -547,6 +568,7 @@ export interface NestedRouteInfo {
 }
 
 export interface AsyncStartedEvent {
+	lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
 	id?: string;
 	asyncDir?: string;
 	pid?: number;
@@ -558,14 +580,18 @@ export interface AsyncStartedEvent {
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	workflowGraph?: WorkflowGraphSnapshot;
+	timeoutMs?: number;
+	deadlineAt?: number;
 	nestedRoute?: NestedRouteInfo;
 }
 
 export interface AsyncStatus {
+	lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
 	runId: string;
 	sessionId?: string;
 	mode: SubagentRunMode;
 	state: "queued" | "running" | "complete" | "failed" | "paused";
+	error?: string;
 	activityState?: ActivityState;
 	lastActivityAt?: number;
 	currentTool?: string;
@@ -576,6 +602,9 @@ export interface AsyncStatus {
 	startedAt: number;
 	endedAt?: number;
 	lastUpdate?: number;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
 	pid?: number;
 	cwd?: string;
 	currentStep?: number;
@@ -606,12 +635,14 @@ export interface AsyncStatus {
 		endedAt?: number;
 		durationMs?: number;
 		exitCode?: number | null;
+		timedOut?: boolean;
 		tokens?: TokenUsage;
 		skills?: string[];
 		model?: string;
 		thinking?: string;
 		attemptedModels?: string[];
 		modelAttempts?: ModelAttempt[];
+		totalCost?: CostSummary;
 		error?: string;
 		structuredOutput?: unknown;
 		structuredOutputPath?: string;
@@ -621,6 +652,7 @@ export interface AsyncStatus {
 	sessionDir?: string;
 	outputFile?: string;
 	totalTokens?: TokenUsage;
+	totalCost?: CostSummary;
 	sessionFile?: string;
 	outputs?: ChainOutputMap;
 }
@@ -655,6 +687,9 @@ export interface AsyncJobState {
 	activeParallelGroup?: boolean;
 	startedAt?: number;
 	updatedAt?: number;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
 	sessionDir?: string;
 	outputFile?: string;
 	totalTokens?: TokenUsage;
@@ -683,6 +718,7 @@ export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
 	subagentInProgress?: boolean;
+	subagentSpawns?: { sessionId: string | null; count: number };
 	asyncJobs: Map<string, AsyncJobState>;
 	foregroundRuns?: Map<string, ForegroundResumeRun>;
 	foregroundControls: Map<string, {
@@ -712,6 +748,8 @@ export interface SubagentState {
 	completionSeen: Map<string, number>;
 	watcher: FSWatcher | null;
 	watcherRestartTimer: ReturnType<typeof setTimeout> | null;
+	companionSuggestionStartupShown?: boolean;
+	companionSuggestionListShown?: boolean;
 	resultFileCoalescer: {
 		schedule(file: string, delayMs?: number): boolean;
 		clear(): void;
@@ -784,6 +822,8 @@ export interface RunSyncOptions {
 	nestedRoute?: NestedRouteInfo;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;
+	/** 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 */
@@ -829,18 +869,41 @@ export interface ProactiveSkillSubagentsConfig {
 	preferredAgent?: string;
 }
 
+export type CompanionSuggestionPackage = "pi-prompt-template-model" | "pi-intercom";
+export type CompanionSuggestionSurface = "session_start" | "list" | "doctor";
+
+export interface CompanionSuggestionPackageConfig {
+	enabled?: boolean;
+	surfaces?: CompanionSuggestionSurface[];
+	dismissed?: {
+		user?: boolean;
+		workspaces?: string[];
+	};
+}
+
+export interface CompanionSuggestionsConfig {
+	enabled?: boolean;
+	packages?: Partial<Record<CompanionSuggestionPackage, CompanionSuggestionPackageConfig>>;
+}
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	forceTopLevelAsync?: boolean;
 	defaultSessionDir?: string;
+	singleRunOutputBaseDir?: string;
 	maxSubagentDepth?: number;
+	maxSubagentSpawnsPerSession?: number;
+	/** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
+	globalConcurrencyLimit?: number;
 	control?: ControlConfig;
 	parallel?: TopLevelParallelConfig;
 	chain?: ExtensionChainConfig;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeBaseDir?: string;
 	intercomBridge?: IntercomBridgeConfig;
 	proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
+	companionSuggestions?: CompanionSuggestionsConfig | false;
 }
 
 // ============================================================================
@@ -923,6 +986,7 @@ 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 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";
@@ -931,6 +995,7 @@ 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 DEFAULT_MAX_SUBAGENT_SPAWNS_PER_SESSION = 40;
 export const SUBAGENT_ACTIONS = ["list", "get", "models", "create", "update", "delete", "status", "interrupt", "resume", "append-step", "doctor"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =
@@ -974,12 +1039,16 @@ export function wrapForkTask(task: string, preamble?: string | false): string {
 // Recursion Depth Guard
 // ============================================================================
 
-export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
+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)
@@ -1008,6 +1077,16 @@ export function getSubagentDepthEnv(maxDepth?: number): Record<string, string> {
 	};
 }
 
+export function normalizeMaxSubagentSpawnsPerSession(value: unknown): number | undefined {
+	return normalizeNonNegativeInteger(value);
+}
+
+export function resolveMaxSubagentSpawnsPerSession(configMaxSpawns?: number): number {
+	return normalizeMaxSubagentSpawnsPerSession(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_SESSION)
+		?? normalizeMaxSubagentSpawnsPerSession(configMaxSpawns)
+		?? DEFAULT_MAX_SUBAGENT_SPAWNS_PER_SESSION;
+}
+
 // ============================================================================
 // Utility Functions
 // ============================================================================

package/src/shared/utils.ts

@@ -5,22 +5,60 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import * as piCodingAgent from "@earendil-works/pi-coding-agent";
 import type { Message } from "@earendil-works/pi-ai";
 import { formatToolCall } from "./formatters.ts";
-import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, SingleResult, ToolCallSummary } from "./types.ts";
+import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, NestedRunSummary, SingleResult, ToolCallSummary, Usage } from "./types.ts";
 
 // ============================================================================
 // File System Utilities
 // ============================================================================
 
 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 function resolveConfigDirName(codingAgentModule: unknown = piCodingAgent): string {
-	const value = codingAgentModule && typeof codingAgentModule === "object"
-		? (codingAgentModule as { CONFIG_DIR_NAME?: unknown }).CONFIG_DIR_NAME
+function validConfigDirName(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function readConfigDirNameFromPackageRoot(packageRoot: string | undefined): string | undefined {
+	if (!packageRoot) return undefined;
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8")) as {
+			name?: unknown;
+			piConfig?: { configDir?: unknown };
+		};
+		if (pkg.name !== PI_CODING_AGENT_PACKAGE_NAME) return undefined;
+		return validConfigDirName(pkg.piConfig?.configDir);
+	} catch {
+		return undefined;
+	}
+}
+
+function resolveConfigDirNameFromPackageJson(entryPoint = process.argv[1], packageRoot = process.env[PI_CODING_AGENT_PACKAGE_ROOT_ENV]): string | undefined {
+	const packageRootValue = readConfigDirNameFromPackageRoot(packageRoot);
+	if (packageRootValue) return packageRootValue;
+	if (!entryPoint) return undefined;
+	try {
+		let dir = path.dirname(fs.realpathSync(entryPoint));
+		while (dir !== path.dirname(dir)) {
+			const value = readConfigDirNameFromPackageRoot(dir);
+			if (value) return value;
+			dir = path.dirname(dir);
+		}
+	} catch {
+		// Package metadata lookup is best-effort; detached runners must not fail here.
+	}
+	return undefined;
+}
+
+export function resolveConfigDirName(codingAgentModule?: unknown, entryPoint?: string, packageRoot?: string): string {
+	const moduleValue = codingAgentModule && typeof codingAgentModule === "object"
+		? validConfigDirName((codingAgentModule as { CONFIG_DIR_NAME?: unknown }).CONFIG_DIR_NAME)
 		: undefined;
-	return typeof value === "string" && value.trim() ? value : DEFAULT_CONFIG_DIR_NAME;
+	return moduleValue
+		?? resolveConfigDirNameFromPackageJson(entryPoint, packageRoot)
+		?? DEFAULT_CONFIG_DIR_NAME;
 }
 
 export function getConfigDirName(): string {
@@ -204,19 +242,28 @@ function writePrompt(agent: string, prompt: string): { dir: string; path: string
  * Get the final text output from a list of messages
  */
 export function getFinalOutput(messages: Message[]): string {
+	const validTextParts: string[] = [];
 	for (let i = messages.length - 1; i >= 0; i--) {
 		const msg = messages[i];
-		if (msg.role === "assistant") {
-			const hasAssistantError = ("errorMessage" in msg && typeof msg.errorMessage === "string" && msg.errorMessage.length > 0)
-				|| ("stopReason" in msg && msg.stopReason === "error");
-			if (hasAssistantError) continue;
-			for (let j = msg.content.length - 1; j >= 0; j--) {
-				const part = msg.content[j];
-				if (part.type === "text" && part.text.trim().length > 0) return part.text;
+		if (msg.role !== "assistant") continue;
+		const hasAssistantError = ("errorMessage" in msg && typeof msg.errorMessage === "string" && msg.errorMessage.length > 0)
+			|| ("stopReason" in msg && msg.stopReason === "error");
+		if (hasAssistantError) continue;
+		for (let j = msg.content.length - 1; j >= 0; j--) {
+			const part = msg.content[j];
+			if (part.type !== "text" || part.text.trim().length === 0) continue;
+			validTextParts.push(part.text);
+			if (/```acceptance-report\s*\n[\s\S]*?```/i.test(part.text)) return part.text;
+			for (const match of part.text.matchAll(/```(?:json|jsonc|json5)\s*\n([\s\S]*?)```/gi)) {
+				const body = match[1] ?? "";
+				if (/"criteriaSatisfied"/.test(body) && /"(?:changedFiles|testsAddedOrUpdated|commandsRun|validationOutput|residualRisks|noStagedFiles|diffSummary|reviewFindings|manualNotes)"/.test(body)) {
+					return part.text;
+				}
 			}
+			if (/ACCEPTANCE_REPORT\s*:/i.test(part.text)) return part.text;
 		}
 	}
-	return "";
+	return validTextParts[0] ?? "";
 }
 
 export function getSingleResultOutput(result: Pick<SingleResult, "finalOutput" | "messages">): string {
@@ -278,6 +325,44 @@ function extractToolCallSummaries(messages: Message[] | undefined): ToolCallSumm
 	return summaries;
 }
 
+export function sumResultsUsage(results: SingleResult[]): Usage {
+	const usage: Usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+	for (const result of results) {
+		usage.input += result.usage.input;
+		usage.output += result.usage.output;
+		usage.cacheRead += result.usage.cacheRead;
+		usage.cacheWrite += result.usage.cacheWrite;
+		usage.cost += result.usage.cost;
+		usage.turns += result.usage.turns;
+	}
+	return usage;
+}
+
+function addNestedCost(total: NonNullable<Details["totalCost"]>, children: NestedRunSummary[] | undefined): void {
+	for (const child of children ?? []) {
+		if (child.totalCost) {
+			total.inputTokens += child.totalCost.inputTokens;
+			total.outputTokens += child.totalCost.outputTokens;
+			total.costUsd += child.totalCost.costUsd;
+			continue;
+		}
+		addNestedCost(total, child.children);
+		for (const step of child.steps ?? []) addNestedCost(total, step.children);
+	}
+}
+
+/** Sum input tokens, output tokens, and cost across a set of SingleResults. */
+export function sumResultsCost(results: SingleResult[]): NonNullable<Details["totalCost"]> {
+	const total = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+	for (const result of results) {
+		total.inputTokens += result.usage.input;
+		total.outputTokens += result.usage.output;
+		total.costUsd += result.usage.cost;
+		addNestedCost(total, result.children);
+	}
+	return total;
+}
+
 export function compactForegroundResult(result: SingleResult): SingleResult {
 	if (result.progress?.status === "running") return result;
 	const toolCalls = result.toolCalls?.length ? result.toolCalls : extractToolCallSummaries(result.messages);