pi-improve-interation 0.0.1

package/node_modules/pi-subagents/src/extension/config.ts

@@ -0,0 +1,235 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Key } from "@earendil-works/pi-tui";
+import { FLEET_KEYBINDING_ACTIONS, type ArtifactDirPreference, type ExtensionConfig } from "../shared/types.ts";
+import { validateMissionStoreConfig } from "../missions/store.ts";
+import { validateAuthorityPolicy } from "../policy/authority.ts";
+import { getAgentDir } from "../shared/utils.ts";
+import { DEFAULT_MODEL_EXCLUSION_TTL_MS, MAX_MODEL_EXCLUSION_TTL_MS, setDefaultTTL } from "../runs/shared/model-exclusions.ts";
+import { validatePermissionConfig } from "../runs/shared/permissions.ts";
+import { MAX_ABANDONED_SLOT_RELEASE_AFTER_MS, MIN_ABANDONED_SLOT_RELEASE_AFTER_MS } from "../runs/background/active-async-capacity.ts";
+
+const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
+const FLEET_KEYBINDING_ACTION_SET = new Set<string>(FLEET_KEYBINDING_ACTIONS);
+const KEY_MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+const BASE_KEY_IDS = new Set([
+	..."abcdefghijklmnopqrstuvwxyz0123456789",
+	...Object.values(Key).flatMap((value) => typeof value === "string" ? [value.toLowerCase()] : []),
+]);
+
+class PrunedForkConfigError extends Error {}
+
+function validateForkContextConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.forkContext must be a JSON object");
+	const config = value as Record<string, unknown>;
+	if (config.mode !== undefined && config.mode !== "full" && config.mode !== "pruned") {
+		throw new Error('config.forkContext.mode must be "full" or "pruned"');
+	}
+	if (config.model !== undefined && (typeof config.model !== "string" || !config.model.trim())) {
+		throw new PrunedForkConfigError("config.forkContext.model must be a non-empty string");
+	}
+	if (config.mode === "pruned" && config.model === undefined) {
+		throw new PrunedForkConfigError('config.forkContext.model is required when config.forkContext.mode is "pruned"');
+	}
+}
+
+function isValidKeyId(value: string): boolean {
+	if (value !== value.trim()) return false;
+	const parts = value.toLowerCase().split("+");
+	const base = parts.pop();
+	if (!base || !BASE_KEY_IDS.has(base)) return false;
+	return parts.length <= KEY_MODIFIERS.size
+		&& new Set(parts).size === parts.length
+		&& parts.every((modifier) => KEY_MODIFIERS.has(modifier));
+}
+
+export function resolveScheduledStoreRoot(value: string): string {
+	const expanded = value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+	if (!path.isAbsolute(expanded)) throw new Error(`config.scheduledRuns.storeRoot must be an absolute path or "~/...", got ${JSON.stringify(value)}`);
+	return path.normalize(expanded);
+}
+
+function validateScheduledRunsConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.scheduledRuns must be a JSON object");
+	const storeRoot = (value as Record<string, unknown>).storeRoot;
+	if (storeRoot === undefined) return;
+	if (typeof storeRoot !== "string" || !storeRoot.trim()) throw new Error("config.scheduledRuns.storeRoot must be a non-empty string");
+	resolveScheduledStoreRoot(storeRoot);
+}
+
+function validateFleetKeybindingsConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.fleetKeybindings must be a JSON object");
+	for (const [action, bindings] of Object.entries(value)) {
+		if (!FLEET_KEYBINDING_ACTION_SET.has(action)) throw new Error(`config.fleetKeybindings.${action} is not a supported Fleet action`);
+		if (!Array.isArray(bindings) || bindings.length === 0) throw new Error(`config.fleetKeybindings.${action} must be a non-empty array of strings`);
+		for (const binding of bindings) {
+			if (typeof binding !== "string" || !binding.trim()) throw new Error(`config.fleetKeybindings.${action} entries must be non-empty strings`);
+		}
+	}
+}
+
+function validateArtifactConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.artifactConfig must be a JSON object");
+	const cleanupDays = (value as Record<string, unknown>).cleanupDays;
+	if (cleanupDays !== undefined && (typeof cleanupDays !== "number" || !Number.isInteger(cleanupDays) || cleanupDays < 0)) {
+		throw new Error("config.artifactConfig.cleanupDays must be a non-negative integer");
+	}
+}
+
+function validateCapacityConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.capacity must be a JSON object");
+	const abandonedSlotReleaseAfterMs = (value as Record<string, unknown>).abandonedSlotReleaseAfterMs;
+	if (abandonedSlotReleaseAfterMs !== undefined
+		&& abandonedSlotReleaseAfterMs !== false
+		&& (typeof abandonedSlotReleaseAfterMs !== "number"
+			|| !Number.isInteger(abandonedSlotReleaseAfterMs)
+			|| abandonedSlotReleaseAfterMs < MIN_ABANDONED_SLOT_RELEASE_AFTER_MS
+			|| abandonedSlotReleaseAfterMs > MAX_ABANDONED_SLOT_RELEASE_AFTER_MS)) {
+		throw new Error(`config.capacity.abandonedSlotReleaseAfterMs must be false or an integer from ${MIN_ABANDONED_SLOT_RELEASE_AFTER_MS} to ${MAX_ABANDONED_SLOT_RELEASE_AFTER_MS}`);
+	}
+}
+
+/** Validate the user-controlled TTL policy before it reaches the exclusion store. */
+// TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
+function validateModelExclusionsConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.modelExclusions must be a JSON object");
+	const defaultTtlMs = (value as Record<string, unknown>).defaultTtlMs;
+	if (defaultTtlMs !== undefined && (typeof defaultTtlMs !== "number" || !Number.isFinite(defaultTtlMs) || defaultTtlMs <= 0 || defaultTtlMs > MAX_MODEL_EXCLUSION_TTL_MS)) {
+		throw new Error(`config.modelExclusions.defaultTtlMs must be a finite positive number no greater than ${MAX_MODEL_EXCLUSION_TTL_MS}`);
+	}
+}
+
+function validateOrcaProgressTabsConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.orcaProgressTabs must be a JSON object");
+	const config = value as Record<string, unknown>;
+	for (const key of Object.keys(config)) {
+		if (key !== "enabled") throw new Error(`config.orcaProgressTabs.${key} is not supported`);
+	}
+	if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
+		throw new Error("config.orcaProgressTabs.enabled must be a boolean");
+	}
+}
+
+function validateMainWindowRendererConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.mainWindowRenderer must be a JSON object");
+	const rendererConfig = value as Record<string, unknown>;
+	if (rendererConfig.horizontalSpacing !== undefined
+		&& (typeof rendererConfig.horizontalSpacing !== "number"
+			|| !Number.isInteger(rendererConfig.horizontalSpacing)
+			|| rendererConfig.horizontalSpacing < 0
+			|| rendererConfig.horizontalSpacing > 4)) {
+		throw new Error("config.mainWindowRenderer.horizontalSpacing must be an integer from 0 to 4");
+	}
+	if (rendererConfig.compactResultMaxLines !== undefined
+		&& (typeof rendererConfig.compactResultMaxLines !== "number"
+			|| !Number.isInteger(rendererConfig.compactResultMaxLines)
+			|| rendererConfig.compactResultMaxLines < 1)) {
+		throw new Error("config.mainWindowRenderer.compactResultMaxLines must be a positive integer");
+	}
+}
+
+function validateConfig(config: Record<string, unknown>): void {
+	if (config.defaultSubagentContext !== undefined && config.defaultSubagentContext !== "fresh" && config.defaultSubagentContext !== "fork") {
+		throw new Error('config.defaultSubagentContext must be "fresh" or "fork"');
+	}
+	validateForkContextConfig(config.forkContext);
+	if (config.foregroundDetachShortcut !== undefined
+		&& (typeof config.foregroundDetachShortcut !== "string" || !isValidKeyId(config.foregroundDetachShortcut))) {
+		throw new Error("config.foregroundDetachShortcut must be a valid keybinding string such as \"ctrl+b\"");
+	}
+	if (config.artifactDir !== undefined && !ARTIFACT_DIR_PREFERENCES.has(config.artifactDir as ArtifactDirPreference)) {
+		throw new Error(`config.artifactDir must be "project", "session", or "temp"`);
+	}
+	if (config.maxActiveAsyncRunsPerSession !== undefined
+		&& (typeof config.maxActiveAsyncRunsPerSession !== "number"
+			|| !Number.isInteger(config.maxActiveAsyncRunsPerSession)
+			|| config.maxActiveAsyncRunsPerSession < 0)) {
+		throw new Error("config.maxActiveAsyncRunsPerSession must be a non-negative integer");
+	}
+	if (config.resultScanLogging !== undefined && config.resultScanLogging !== "all" && config.resultScanLogging !== "activity" && config.resultScanLogging !== "off") {
+		throw new Error('config.resultScanLogging must be "all", "activity", or "off"');
+	}
+	validateMissionStoreConfig(config.missions);
+	validateAuthorityPolicy(config.authorityPolicy);
+	validatePermissionConfig(config.permissions);
+	validateScheduledRunsConfig(config.scheduledRuns);
+	validateFleetKeybindingsConfig(config.fleetKeybindings);
+	validateArtifactConfig(config.artifactConfig);
+	validateCapacityConfig(config.capacity);
+	validateModelExclusionsConfig(config.modelExclusions);
+	validateMainWindowRendererConfig(config.mainWindowRenderer);
+	validateOrcaProgressTabsConfig(config.orcaProgressTabs);
+}
+
+export function getConfigPath(): string {
+	return path.join(getAgentDir(), "extensions", "subagent", "config.json");
+}
+
+function readConfigForUpdate(configPath = getConfigPath()): ExtensionConfig {
+	if (!fs.existsSync(configPath)) return {};
+	const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`Subagent config at '${configPath}' must be a JSON object`);
+	}
+	validateConfig(parsed as Record<string, unknown>);
+	return parsed as ExtensionConfig;
+}
+
+export function saveConfig(config: ExtensionConfig, configPath = getConfigPath()): void {
+	fs.mkdirSync(path.dirname(configPath), { recursive: true });
+	fs.writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`, "utf-8");
+}
+
+export function updateConfig(updater: (config: ExtensionConfig) => ExtensionConfig): ExtensionConfig {
+	const configPath = getConfigPath();
+	const next = updater(readConfigForUpdate(configPath));
+	validateConfig(next as Record<string, unknown>);
+	saveConfig(next, configPath);
+	return next;
+}
+
+/**
+ * Resolve the default TTL that the process-wide exclusion store should use.
+ *
+ * @param config Extension configuration after validation.
+ * @returns The configured TTL in milliseconds, or the built-in 24-hour default.
+ */
+// TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
+export function resolveModelExclusionTTL(config: Pick<ExtensionConfig, "modelExclusions">): number {
+	return config.modelExclusions?.defaultTtlMs ?? DEFAULT_MODEL_EXCLUSION_TTL_MS;
+}
+
+/**
+ * Apply the configured exclusion policy to the process-wide model store.
+ *
+ * @param config Extension configuration after validation.
+ * @returns Nothing.
+ */
+// TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
+export function applyModelExclusionsConfig(config: Pick<ExtensionConfig, "modelExclusions">): void {
+	setDefaultTTL(resolveModelExclusionTTL(config), { shortenExisting: config.modelExclusions?.defaultTtlMs !== undefined });
+}
+
+export function resolveAsyncByDefault(config: Pick<ExtensionConfig, "asyncByDefault">): boolean {
+	return config.asyncByDefault !== false;
+}
+
+export function loadConfig(): ExtensionConfig {
+	const configPath = getConfigPath();
+	try {
+		return readConfigForUpdate(configPath);
+	} catch (error) {
+		if (error instanceof PrunedForkConfigError) throw error;
+		console.error(`Failed to load subagent config from '${configPath}':`, error);
+	}
+	return {};
+}

package/node_modules/pi-subagents/src/extension/control-notices.ts

@@ -0,0 +1,58 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { controlNotificationKey, formatControlNoticeMessage } from "../runs/shared/subagent-control.ts";
+import type { ControlEvent, SubagentState } from "../shared/types.ts";
+
+export const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
+
+export interface SubagentControlMessageDetails {
+	event: ControlEvent;
+	source?: "foreground" | "async" | "goal";
+	asyncDir?: string;
+	childIntercomTarget?: string;
+	noticeText?: string;
+}
+
+export function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
+	return details.childIntercomTarget;
+}
+
+export function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
+	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
+}
+
+function deliverControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+}): void {
+	const childIntercomTarget = controlNoticeTarget(input.details);
+	const key = controlNotificationKey(input.details.event, childIntercomTarget);
+	if (input.visibleControlNotices.has(key)) return;
+	input.visibleControlNotices.add(key);
+	const noticeText = input.details.noticeText ?? formatControlNoticeMessage(input.details.event, childIntercomTarget);
+	input.pi.sendMessage(
+		{
+			customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
+			content: noticeText,
+			display: true,
+			details: { ...input.details, childIntercomTarget, noticeText },
+		},
+		{ triggerTurn: input.details.source === "async" },
+	);
+}
+
+export function handleSubagentControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	state: SubagentState;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+}): void {
+	if (!input.details?.event || input.details.event.type === "active_long_running") return;
+	if (input.details.source === "foreground") {
+		// A foreground tool blocks Pi from displaying this message. The run can
+		// finish before Pi flushes it, and queued messages cannot be withdrawn.
+		// Foreground control remains available through the live tool and fleet state.
+		return;
+	}
+	deliverControlNotice(input);
+}

package/node_modules/pi-subagents/src/extension/doctor.ts

@@ -0,0 +1,278 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
+import { isAsyncAvailable } from "../runs/background/async-execution.ts";
+import { formatSpawnBudgetSummary, getSpawnBudgetSnapshot } from "../runs/shared/spawn-budget.ts";
+import { getActiveAsyncCapacitySnapshot, resolveAbandonedSlotReleaseAfterMs, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
+import { decodeRunFanoutBudgetDescriptor, formatRunFanoutBudget, getRunFanoutBudgetSnapshot, RUN_FANOUT_BUDGET_ENV } from "../runs/shared/run-fanout-budget.ts";
+import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
+import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
+import {
+	DIRS,
+	CHAIN_RUNS_DIR,
+	TEMP_ROOT_DIR,
+	type ExtensionConfig,
+	type SubagentState,
+	normalizeMaxSubagentSpawnsPerRun,
+	resolveMaxSubagentSpawnsPerRun,
+} from "../shared/types.ts";
+
+interface DoctorPaths {
+	tempRootDir: string;
+	asyncDir: string;
+	resultsDir: string;
+	chainRunsDir: string;
+}
+
+interface DoctorDeps {
+	isAsyncAvailable: () => boolean;
+	discoverAgentsAll: typeof discoverAgentsAll;
+	discoverAvailableSkills: typeof discoverAvailableSkills;
+	diagnoseIntercomBridge: typeof diagnoseIntercomBridge;
+}
+
+interface DoctorReportInput {
+	cwd: string;
+	config: ExtensionConfig;
+	state: SubagentState;
+	context?: "fresh" | "fork";
+	requestedSessionDir?: string;
+	currentSessionFile?: string | null;
+	currentSessionId?: string | null;
+	orchestratorTarget?: string;
+	sessionError?: string;
+	expandTilde?: (value: string) => string;
+	paths?: DoctorPaths;
+	deps?: Partial<DoctorDeps>;
+}
+
+function defaultPaths(): DoctorPaths {
+	return {
+		tempRootDir: TEMP_ROOT_DIR,
+		asyncDir: DIRS.async,
+		resultsDir: DIRS.results,
+		chainRunsDir: CHAIN_RUNS_DIR,
+	};
+}
+
+const DEFAULT_DEPS: DoctorDeps = {
+	isAsyncAvailable,
+	discoverAgentsAll,
+	discoverAvailableSkills,
+	diagnoseIntercomBridge,
+};
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+
+function lineFromCheck(label: string, check: () => string): string {
+	try {
+		return check();
+	} catch (error) {
+		return `- ${label}: failed — ${errorText(error)}`;
+	}
+}
+
+function formatExistingDirectory(label: string, dirPath: string): string {
+	try {
+		if (!fs.existsSync(dirPath)) return `- ${label}: missing (${dirPath})`;
+		const stats = fs.statSync(dirPath);
+		if (!stats.isDirectory()) throw new Error(`not a directory: ${dirPath}`);
+		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+		return `- ${label}: ok (${dirPath})`;
+	} catch (error) {
+		return `- ${label}: failed (${dirPath}) — ${errorText(error)}`;
+	}
+}
+
+function formatSourceCounts(counts: Record<AgentSource, number>): string {
+	return `builtin ${counts.builtin}, package ${counts.package}, user ${counts.user}, project ${counts.project}`;
+}
+
+function formatSkillSourceCounts(skills: Array<{ source: SkillSource }>): string {
+	const counts = new Map<SkillSource, number>();
+	for (const skill of skills) counts.set(skill.source, (counts.get(skill.source) ?? 0) + 1);
+	const ordered: SkillSource[] = [
+		"project",
+		"project-settings",
+		"project-package",
+		"user",
+		"user-settings",
+		"user-package",
+		"extension",
+		"builtin",
+		"unknown",
+	];
+	const parts = ordered
+		.map((source) => `${source} ${counts.get(source) ?? 0}`)
+		.filter((part) => !part.endsWith(" 0"));
+	return parts.length > 0 ? parts.join(", ") : "none";
+}
+
+function formatConfiguredSessionDir(input: DoctorReportInput): string {
+	if (input.requestedSessionDir) {
+		return path.resolve(input.expandTilde?.(input.requestedSessionDir) ?? input.requestedSessionDir);
+	}
+	if (input.config.defaultSessionDir) {
+		return path.resolve(input.expandTilde?.(input.config.defaultSessionDir) ?? input.config.defaultSessionDir);
+	}
+	return "not configured";
+}
+
+function formatSessionLines(input: DoctorReportInput): string[] {
+	const sessionFile = input.currentSessionFile ?? null;
+	const lines = [
+		lineFromCheck("configured session dir", () => `- configured session dir: ${formatConfiguredSessionDir(input)}`),
+		`- current session file: ${sessionFile ?? "not available"}`,
+		`- current session dir: ${sessionFile ? path.dirname(sessionFile) : "not available"}`,
+		`- current session id: ${input.currentSessionId ?? input.state.currentSessionId ?? "not available"}`,
+	];
+	if (input.sessionError) lines.push(`- session manager: failed — ${input.sessionError}`);
+	return lines;
+}
+
+function formatDiscovery(input: DoctorReportInput, deps: DoctorDeps): string[] {
+	return [
+		lineFromCheck("agents", () => {
+			const discovered = deps.discoverAgentsAll(input.cwd);
+			const agentCounts = {
+				builtin: discovered.builtin.length,
+				package: discovered.package?.length ?? 0,
+				user: discovered.user.length,
+				project: discovered.project.length,
+				runtime: 0,
+			};
+			const diagnostics = discovered.agentDiagnostics ?? [];
+			return [
+				`- agents: total ${agentCounts.builtin + agentCounts.package + agentCounts.user + agentCounts.project} (${formatSourceCounts(agentCounts)})`,
+				...diagnostics.map((diagnostic) => `- invalid agent ${diagnostic.name ?? diagnostic.filePath} (${diagnostic.source}): ${diagnostic.error}`),
+			].join("\n");
+		}),
+		lineFromCheck("skills", () => {
+			const skills = deps.discoverAvailableSkills(input.cwd);
+			return `- skills: total ${skills.length} (${formatSkillSourceCounts(skills)})`;
+		}),
+	];
+}
+
+function formatIntercomDiagnostic(diagnostic: IntercomBridgeDiagnostic, context: "fresh" | "fork" | undefined): string[] {
+	const lines = [
+		`- bridge: ${diagnostic.active ? "active" : "inactive"}${diagnostic.reason ? ` (${diagnostic.reason})` : ""}`,
+		`- mode: ${diagnostic.mode}; context: ${context ?? "unspecified"}`,
+		`- orchestrator target: ${diagnostic.orchestratorTarget ?? "not available"}`,
+		`- supervisor channel: ${diagnostic.supervisorChannelAvailable ? "available" : "unavailable"} (${diagnostic.extensionDir})`,
+	];
+	return lines;
+}
+
+function formatSpawnBudgetSection(input: DoctorReportInput): string[] {
+	const snapshot = getSpawnBudgetSnapshot(input.state, input.config, input.currentSessionId ?? input.state.currentSessionId);
+	return [
+		`- usage: ${formatSpawnBudgetSummary(snapshot)}`,
+		`- recent grants: ${snapshot.grantHistory.length === 0
+			? "none"
+			: snapshot.grantHistory.map((grant) => `+${grant.amount} at ${new Date(grant.grantedAt).toISOString()} (${grant.previousLimit} → ${grant.limit})`).join("; ")}`,
+		"- reset boundary: a new parent session resets usage and grants; compaction does not",
+	];
+}
+
+function formatRunFanoutSection(input: DoctorReportInput): string[] {
+	try {
+		const inherited = decodeRunFanoutBudgetDescriptor(process.env[RUN_FANOUT_BUDGET_ENV]);
+		if (inherited) {
+			return [`- usage: ${formatRunFanoutBudget(getRunFanoutBudgetSnapshot(inherited)).replace(/^Run fan-out: /, "")}`, `- root run: ${inherited.rootRunId}`, "- reset boundary: cumulative claims are never released; a new top-level run creates a new budget"];
+		}
+	} catch (error) {
+		return [`- inherited budget: invalid — ${errorText(error)}`];
+	}
+	const configured = resolveMaxSubagentSpawnsPerRun(input.config.maxSubagentSpawnsPerRun);
+	const source = normalizeMaxSubagentSpawnsPerRun(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_RUN) !== undefined
+		? "environment"
+		: normalizeMaxSubagentSpawnsPerRun(input.config.maxSubagentSpawnsPerRun) !== undefined ? "config" : "default";
+	return [`- configured limit: ${configured} (${source})`, "- usage: available after a run starts", "- reset boundary: cumulative claims are never released; a new top-level run creates a new budget"];
+}
+
+function formatActiveAsyncCapacitySection(input: DoctorReportInput): string[] {
+	const limit = resolveMaxActiveAsyncRunsPerSession(input.config.maxActiveAsyncRunsPerSession);
+	const sessionId = input.currentSessionId ?? input.state.currentSessionId;
+	const snapshot = sessionId
+		? getActiveAsyncCapacitySnapshot(sessionId, limit, { liveWorkflowRunIds: new Set(input.state.workflowControllers?.keys() ?? []), abandonedSlotReleaseAfterMs: resolveAbandonedSlotReleaseAfterMs(input.config.capacity?.abandonedSlotReleaseAfterMs) })
+		: { used: 0, limit: limit ?? 0 };
+	input.state.activeAsyncCapacity = snapshot;
+	return [
+		`- usage: ${snapshot.used}/${snapshot.limit || "unlimited"} used`,
+		"- scope: top-level async runs in the current parent session; foreground and nested workflow children are not charged again",
+		"- release: terminal state plus matching observed process-terminal proof, or abandoned-timeout for failed runs with a dead runner PID and stale activity when enabled; false keeps unknown-proof slots",
+	];
+}
+
+function formatPermissionSystemSection(): string[] {
+	const lines: string[] = [];
+	const parentSession = process.env["PI_SUBAGENT_PARENT_SESSION"] ?? "";
+	const trimmed = parentSession.trim();
+	if (trimmed) {
+		lines.push(`- parent session: set (${trimmed})`);
+	} else {
+		lines.push("- parent session: not set — ask forwarding from subprocess children will not reach a parent UI");
+	}
+	const isChild = process.env["PI_SUBAGENT_CHILD"] === "1";
+	lines.push(`- subagent process: ${isChild ? "yes (PI_SUBAGENT_CHILD=1)" : "no"}`);
+	// Whether pi-permission-system is installed and where it stores config is
+	// outside pi-subagents' control, so we only report the forwarding signal we
+	// own. Run `pi list` to confirm the permission extension is installed.
+	return lines;
+}
+
+function formatWorkflowScriptSection(): string[] {
+	return [
+		"- helpers: runs.run, runs.all, runs.steer, runs.status, runs.ref/refs, emit, console",
+		"- recovery: if runs.all is missing, reload or update pi-subagents; await Promise.all([runs.run(...)]) is also supported",
+	];
+}
+
+export function buildDoctorReport(input: DoctorReportInput): string {
+	const paths = input.paths ?? defaultPaths();
+	const deps = { ...DEFAULT_DEPS, ...input.deps };
+	const lines = [
+		"Subagents doctor report",
+		"",
+		"Runtime",
+		`- cwd: ${input.cwd}`,
+		lineFromCheck("async support", () => `- async support: ${deps.isAsyncAvailable() ? "available" : "unavailable"}`),
+		...formatSessionLines(input),
+		"",
+		"Filesystem",
+		formatExistingDirectory("temp root", paths.tempRootDir),
+		formatExistingDirectory("async runs", paths.asyncDir),
+		formatExistingDirectory("results", paths.resultsDir),
+		formatExistingDirectory("chain runs", paths.chainRunsDir),
+		"",
+		"Discovery",
+		...formatDiscovery(input, deps),
+		"",
+		"Spawn budget",
+		...formatSpawnBudgetSection(input),
+		"",
+		"Run fan-out budget",
+		...formatRunFanoutSection(input),
+		"",
+		"Active async capacity",
+		...formatActiveAsyncCapacitySection(input),
+		"",
+		"Workflow script",
+		...formatWorkflowScriptSection(),
+		"",
+		"Permission system",
+		...formatPermissionSystemSection(),
+		"",
+		"Intercom bridge",
+		...lineFromCheck("intercom bridge", () => formatIntercomDiagnostic(deps.diagnoseIntercomBridge({
+			config: input.config.intercomBridge,
+			context: input.context,
+			orchestratorTarget: input.orchestratorTarget,
+			cwd: input.cwd,
+		}), input.context).join("\n")).split("\n"),
+	];
+	return lines.join("\n");
+}