pi-cohort 2.0.0

package/src/runs/shared/run-history.ts

@@ -0,0 +1,60 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "../../shared/utils.ts";
+
+export interface RunEntry {
+	agent: string;
+	task: string;
+	ts: number;
+	status: "ok" | "error";
+	duration: number;
+	exit?: number;
+}
+
+const ROTATE_READ_THRESHOLD = 1200;
+const ROTATE_KEEP = 1000;
+
+function getHistoryPath(): string {
+	return path.join(getAgentDir(), "run-history.jsonl");
+}
+
+export function recordRun(agent: string, task: string, exitCode: number, durationMs: number): void {
+	try {
+		const entry: RunEntry = {
+			agent,
+			task: task.slice(0, 200),
+			ts: Math.floor(Date.now() / 1000),
+			status: exitCode === 0 ? "ok" : "error",
+			duration: durationMs,
+			...(exitCode !== 0 ? { exit: exitCode } : {}),
+		};
+		const historyPath = getHistoryPath();
+		fs.mkdirSync(path.dirname(historyPath), { recursive: true });
+		fs.appendFileSync(historyPath, `${JSON.stringify(entry)}\n`);
+	} catch {
+		// Best-effort — never crash the execution flow for history recording
+	}
+}
+
+export function loadRunsForAgent(agent: string): RunEntry[] {
+	const historyPath = getHistoryPath();
+	if (!fs.existsSync(historyPath)) return [];
+	let raw: string;
+	try {
+		raw = fs.readFileSync(historyPath, "utf-8");
+	} catch {
+		return [];
+	}
+
+	let lines = raw.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+
+	if (lines.length > ROTATE_READ_THRESHOLD) {
+		lines = lines.slice(-ROTATE_KEEP);
+		try { fs.writeFileSync(historyPath, `${lines.join("\n")}\n`, "utf-8"); } catch {}
+	}
+
+	return lines
+		.map((line) => { try { return JSON.parse(line) as RunEntry; } catch { return undefined; } })
+		.filter((entry): entry is RunEntry => Boolean(entry) && entry.agent === agent)
+		.reverse();
+}

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

@@ -0,0 +1,164 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
+
+export interface SingleOutputSnapshot {
+	exists: boolean;
+	mtimeMs?: number;
+	size?: number;
+}
+
+export function normalizeSingleOutputOverride(
+	output: string | boolean | undefined,
+	defaultOutput: string | undefined,
+): string | false | undefined {
+	if (output === false || output === "false") return false;
+	if (output === true || output === "true") return defaultOutput;
+	if (typeof output === "string" && output.length > 0) return output;
+	return undefined;
+}
+
+export function resolveSingleOutputPath(
+	output: string | boolean | undefined,
+	runtimeCwd: string,
+	requestedCwd?: string,
+): string | undefined {
+	if (typeof output !== "string" || !output || output === "false" || output === "true") return undefined;
+	if (path.isAbsolute(output)) return output;
+	const baseCwd = requestedCwd
+		? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))
+		: runtimeCwd;
+	return path.resolve(baseCwd, output);
+}
+
+export function injectSingleOutputInstruction(task: string, outputPath: string | undefined): string {
+	if (!outputPath) return task;
+	return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;
+}
+
+function countLines(text: string): number {
+	if (!text) return 0;
+	const newlineMatches = text.match(/\r\n|\r|\n/g);
+	return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+
+function formatByteSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let value = bytes / 1024;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+export function formatSavedOutputReference(savedPath: string, fullOutput: string): SavedOutputReference {
+	const absolutePath = path.resolve(savedPath);
+	const bytes = Buffer.byteLength(fullOutput, "utf-8");
+	const lines = countLines(fullOutput);
+	return {
+		path: absolutePath,
+		bytes,
+		lines,
+		message: `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`,
+	};
+}
+
+export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, outputPath: string | undefined, context: string): string | undefined {
+	if (outputMode === "file-only" && !outputPath) {
+		return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;
+	}
+	return undefined;
+}
+
+export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
+	if (!outputPath) return undefined;
+	try {
+		const stat = fs.statSync(outputPath);
+		return { exists: true, mtimeMs: stat.mtimeMs, size: stat.size };
+	} catch {
+		// The snapshot is advisory; resolveSingleOutput reports concrete read/write failures.
+		return { exists: false };
+	}
+}
+
+function persistSingleOutput(
+	outputPath: string | undefined,
+	fullOutput: string,
+): { savedPath?: string; error?: string } {
+	if (!outputPath) return {};
+	try {
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, fullOutput, "utf-8");
+		return { savedPath: outputPath };
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export function resolveSingleOutput(
+	outputPath: string | undefined,
+	fallbackOutput: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): { fullOutput: string; savedPath?: string; saveError?: string } {
+	if (!outputPath) return { fullOutput: fallbackOutput };
+
+	let changedSinceStart = false;
+	try {
+		const stat = fs.statSync(outputPath);
+		changedSinceStart = !beforeRun?.exists
+			|| stat.mtimeMs !== beforeRun.mtimeMs
+			|| stat.size !== beforeRun.size;
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+		if (code !== "ENOENT" && code !== "ENOTDIR") {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to inspect output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	if (changedSinceStart) {
+		try {
+			return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
+		} catch (error) {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to read changed output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	const save = persistSingleOutput(outputPath, fallbackOutput);
+	if (save.savedPath) return { fullOutput: fallbackOutput, savedPath: save.savedPath };
+	return { fullOutput: fallbackOutput, saveError: save.error };
+}
+
+export function finalizeSingleOutput(params: {
+	fullOutput: string;
+	truncatedOutput?: string;
+	outputPath?: string;
+	outputMode?: OutputMode;
+	exitCode: number;
+	savedPath?: string;
+	outputReference?: SavedOutputReference;
+	saveError?: string;
+}): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
+	let displayOutput = params.truncatedOutput || params.fullOutput;
+	if (params.exitCode === 0 && params.savedPath) {
+		const outputReference = params.outputReference ?? formatSavedOutputReference(params.savedPath, params.fullOutput);
+		if (params.outputMode === "file-only") {
+			return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
+		}
+		displayOutput += `\n\n${outputReference.message}`;
+		return { displayOutput, savedPath: params.savedPath, outputReference };
+	}
+	if (params.exitCode === 0 && params.saveError && params.outputPath) {
+		displayOutput += `\n\nOutput file error: ${params.outputPath}\n${params.saveError}`;
+		return { displayOutput, saveError: params.saveError };
+	}
+	return { displayOutput };
+}

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

@@ -0,0 +1,77 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Compile } from "typebox/compile";
+import type { JsonSchemaObject } from "../../shared/types.ts";
+
+export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
+export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
+
+export interface StructuredOutputRuntime {
+	schema: JsonSchemaObject;
+	schemaPath: string;
+	outputPath: string;
+}
+
+interface CompiledJsonSchema {
+	Check(value: unknown): boolean;
+	Errors(value: unknown): Iterable<{ instancePath?: string; message?: string }>;
+}
+
+export function assertJsonSchemaObject(schema: unknown, label = "outputSchema"): asserts schema is JsonSchemaObject {
+	if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+		throw new Error(`${label} must be a JSON Schema object.`);
+	}
+}
+
+export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string): StructuredOutputRuntime {
+	assertJsonSchemaObject(schema);
+	const rootDir = baseDir ?? os.tmpdir();
+	fs.mkdirSync(rootDir, { recursive: true });
+	const dir = fs.mkdtempSync(path.join(rootDir, "pi-subagent-structured-"));
+	const schemaPath = path.join(dir, "schema.json");
+	const outputPath = path.join(dir, "output.json");
+	fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
+	return { schema, schemaPath, outputPath };
+}
+
+export function validateStructuredOutputValue(schema: JsonSchemaObject, value: unknown): { status: "valid" } | { status: "invalid"; message: string } {
+	let validator: CompiledJsonSchema;
+	try {
+		validator = (Compile as (schema: unknown) => CompiledJsonSchema)(schema);
+	} catch (error) {
+		return { status: "invalid", message: `invalid outputSchema: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	if (validator.Check(value)) return { status: "valid" };
+	const errors = [...validator.Errors(value)]
+		.slice(0, 8)
+		.map((error) => {
+			const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
+			return `${pathText}: ${error.message}`;
+		});
+	return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
+}
+
+export function readStructuredOutput(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
+	if (!fs.existsSync(runtime.outputPath)) {
+		return { error: "Missing structured_output call; this step has outputSchema and must finish by calling structured_output." };
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8"));
+	} catch (error) {
+		return { error: `Failed to read structured output: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	const validation = validateStructuredOutputValue(runtime.schema, value);
+	if (validation.status === "invalid") return { error: `Structured output validation failed: ${validation.message}` };
+	return { value };
+}
+
+export function cleanupStructuredOutputRuntime(runtime: StructuredOutputRuntime | undefined): void {
+	if (!runtime) return;
+	try {
+		fs.rmSync(path.dirname(runtime.schemaPath), { recursive: true, force: true });
+	} catch {
+		// Best-effort temp cleanup.
+	}
+}

package/src/runs/shared/subagent-control.ts

@@ -0,0 +1,287 @@
+import {
+	type ActivityState,
+	type ControlConfig,
+	type ControlEvent,
+	type ControlEventType,
+	type ControlNotificationChannel,
+	type ResolvedControlConfig,
+} from "../../shared/types.ts";
+
+const CONTROL_EVENT_TYPES: ControlEventType[] = ["active_long_running", "needs_attention"];
+const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
+const DEFAULT_NOTIFY_ON: ControlEventType[] = ["active_long_running", "needs_attention"];
+
+export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
+	enabled: true,
+	needsAttentionAfterMs: 60_000,
+	activeNoticeAfterMs: 240_000,
+	inFlightSilenceCeilingMs: 600_000,
+	inFlightSilenceKillMs: 1_800_000,
+	failedToolAttemptsBeforeAttention: 3,
+	notifyOn: DEFAULT_NOTIFY_ON,
+	notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
+};
+
+function parsePositiveInt(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) return undefined;
+	return value;
+}
+
+function parseControlList<T extends string>(value: unknown, allowed: readonly T[]): T[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	if (value.length === 0) return [];
+	const allowedSet = new Set(allowed);
+	const parsed = value.filter((entry): entry is T => typeof entry === "string" && allowedSet.has(entry as T));
+	return parsed.length > 0 ? Array.from(new Set(parsed)) : undefined;
+}
+
+export function resolveControlConfig(
+	globalConfig?: ControlConfig,
+	override?: ControlConfig,
+): ResolvedControlConfig {
+	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
+	const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
+		?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
+	const activeNoticeAfterMs = parsePositiveInt(override?.activeNoticeAfterMs)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.activeNoticeAfterMs;
+	const inFlightSilenceCeilingMs = parsePositiveInt(override?.inFlightSilenceCeilingMs)
+		?? parsePositiveInt(globalConfig?.inFlightSilenceCeilingMs)
+		?? DEFAULT_CONTROL_CONFIG.inFlightSilenceCeilingMs;
+	const resolvedInFlightSilenceKillMs = parsePositiveInt(override?.inFlightSilenceKillMs)
+		?? parsePositiveInt(globalConfig?.inFlightSilenceKillMs)
+		?? DEFAULT_CONTROL_CONFIG.inFlightSilenceKillMs;
+	const inFlightSilenceKillMs = Math.max(
+		resolvedInFlightSilenceKillMs,
+		inFlightSilenceCeilingMs + needsAttentionAfterMs,
+	);
+	const activeNoticeAfterTurns = parsePositiveInt(override?.activeNoticeAfterTurns)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterTurns);
+	const activeNoticeAfterTokens = parsePositiveInt(override?.activeNoticeAfterTokens)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterTokens);
+	const failedToolAttemptsBeforeAttention = parsePositiveInt(override?.failedToolAttemptsBeforeAttention)
+		?? parsePositiveInt(globalConfig?.failedToolAttemptsBeforeAttention)
+		?? DEFAULT_CONTROL_CONFIG.failedToolAttemptsBeforeAttention;
+	const notifyOn = parseControlList(override?.notifyOn, CONTROL_EVENT_TYPES)
+		?? parseControlList(globalConfig?.notifyOn, CONTROL_EVENT_TYPES)
+		?? DEFAULT_CONTROL_CONFIG.notifyOn;
+	const notifyChannels = parseControlList(override?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? parseControlList(globalConfig?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? DEFAULT_CONTROL_CONFIG.notifyChannels;
+	return {
+		enabled,
+		needsAttentionAfterMs,
+		activeNoticeAfterMs,
+		inFlightSilenceCeilingMs,
+		inFlightSilenceKillMs,
+		activeNoticeAfterTurns,
+		activeNoticeAfterTokens,
+		failedToolAttemptsBeforeAttention,
+		notifyOn: [...notifyOn],
+		notifyChannels: [...notifyChannels],
+	};
+}
+
+export interface TurnLifecycleState {
+	turnOpen?: boolean;
+	lastProductiveSignalAt?: number;
+}
+
+export function applyChildEventToLifecycle(
+	state: TurnLifecycleState,
+	event: { type?: string; hasToolCall?: boolean },
+	now: number,
+): TurnLifecycleState {
+	switch (event.type) {
+		case "turn_start":
+		case "message_start":
+			return { turnOpen: true, lastProductiveSignalAt: state.lastProductiveSignalAt };
+		case "message_update":
+		case "tool_execution_start":
+		case "tool_execution_end":
+		case "tool_result_end":
+			return { turnOpen: state.turnOpen, lastProductiveSignalAt: now };
+		case "message_end":
+			return { turnOpen: event.hasToolCall ? state.turnOpen : false, lastProductiveSignalAt: now };
+		case "turn_end":
+			return { turnOpen: false, lastProductiveSignalAt: now };
+		default:
+			return state;
+	}
+}
+
+export function deriveActivityState(input: {
+	config: ResolvedControlConfig;
+	startedAt: number;
+	lastActivityAt?: number;
+	now?: number;
+	inFlightTurn?: boolean;
+	lastProductiveSignalAt?: number;
+}): ActivityState | undefined {
+	if (!input.config.enabled) return undefined;
+	const now = input.now ?? Date.now();
+	const lastActivity = input.lastActivityAt ?? input.startedAt;
+	const ageMs = Math.max(0, now - lastActivity);
+	if (ageMs <= input.config.needsAttentionAfterMs) return undefined;
+	if (input.inFlightTurn) {
+		const silenceMs = Math.max(0, now - (input.lastProductiveSignalAt ?? input.startedAt));
+		return silenceMs > input.config.inFlightSilenceCeilingMs ? "needs_attention" : "active_long_running";
+	}
+	return "needs_attention";
+}
+
+export function shouldSilenceKill(input: {
+	turnOpen?: boolean;
+	lastProductiveSignalAt?: number;
+	startedAt: number;
+	now: number;
+	killMs: number;
+}): boolean {
+	if (!input.turnOpen) return false;
+	const silenceMs = input.now - (input.lastProductiveSignalAt ?? input.startedAt);
+	return silenceMs > input.killMs;
+}
+
+export function buildControlEvent(input: {
+	type?: ControlEventType;
+	from?: ActivityState;
+	to: ActivityState;
+	runId: string;
+	agent: string;
+	index?: number;
+	ts?: number;
+	lastActivityAt?: number;
+	message?: string;
+	reason?: ControlEvent["reason"];
+	turns?: number;
+	tokens?: number;
+	toolCount?: number;
+	currentTool?: string;
+	currentToolDurationMs?: number;
+	currentPath?: string;
+	elapsedMs?: number;
+	recentFailureSummary?: string;
+}): ControlEvent {
+	const ts = input.ts ?? Date.now();
+	const type = input.type ?? (input.to === "active_long_running" ? "active_long_running" : "needs_attention");
+	const elapsedMs = input.elapsedMs ?? (input.lastActivityAt ? Math.max(0, ts - input.lastActivityAt) : undefined);
+	const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
+	const message = input.message ?? (type === "active_long_running"
+		? `${input.agent} is still active but long-running`
+		: elapsedSeconds !== undefined
+			? `${input.agent} needs attention (no observed activity for ${elapsedSeconds}s)`
+			: `${input.agent} needs attention`);
+	return {
+		type,
+		...(input.from ? { from: input.from } : {}),
+		to: input.to,
+		ts,
+		runId: input.runId,
+		agent: input.agent,
+		...(input.index !== undefined ? { index: input.index } : {}),
+		message,
+		reason: input.reason ?? (type === "active_long_running" ? "active_long_running" : "idle"),
+		...(input.turns !== undefined ? { turns: input.turns } : {}),
+		...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+		...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
+		...(input.currentTool ? { currentTool: input.currentTool } : {}),
+		...(input.currentToolDurationMs !== undefined ? { currentToolDurationMs: input.currentToolDurationMs } : {}),
+		...(input.currentPath ? { currentPath: input.currentPath } : {}),
+		...(elapsedMs !== undefined ? { elapsedMs } : {}),
+		...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
+	};
+}
+
+export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: ControlEvent): boolean {
+	return config.enabled && config.notifyOn.includes(event.type);
+}
+
+export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
+	const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
+	return `${childKey}:${event.type}:${event.reason ?? "idle"}`;
+}
+
+export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
+	if (!shouldNotifyControlEvent(config, event)) return false;
+	const key = controlNotificationKey(event, childIntercomTarget);
+	if (seenKeys.has(key)) return false;
+	seenKeys.add(key);
+	return true;
+}
+
+function formatLongRunningFacts(event: ControlEvent): string | undefined {
+	const facts: string[] = [];
+	if (event.elapsedMs !== undefined) facts.push(`elapsed ${Math.floor(Math.max(0, event.elapsedMs) / 1000)}s`);
+	if (event.turns !== undefined) facts.push(`${event.turns} turns`);
+	if (event.tokens !== undefined) facts.push(`${event.tokens} tokens`);
+	if (event.toolCount !== undefined) facts.push(`${event.toolCount} tools`);
+	if (event.currentTool) facts.push(`tool ${event.currentTool}${event.currentToolDurationMs !== undefined ? ` ${Math.floor(Math.max(0, event.currentToolDurationMs) / 1000)}s` : ""}`);
+	if (event.currentPath) facts.push(`path ${event.currentPath}`);
+	return facts.length > 0 ? facts.join(" | ") : undefined;
+}
+
+export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	const runTarget = event.runId;
+	if (event.reason === "completion_guard") {
+		return [
+			`Subagent failed: ${event.agent}`,
+			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+			`Signal: ${event.message}`,
+			"Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
+			childIntercomTarget ? `Run intercom target (may be inactive): ${childIntercomTarget}` : undefined,
+		].filter((line): line is string => Boolean(line)).join("\n");
+	}
+
+	const nudgeCommand = childIntercomTarget
+		? `intercom({ action: "send", to: "${childIntercomTarget}", message: "What are you blocked on? Reply with the smallest next step or ask for a decision." })`
+		: undefined;
+	if (event.type === "active_long_running") {
+		const facts = formatLongRunningFacts(event);
+		return [
+			`Subagent active but long-running: ${event.agent}`,
+			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+			`Signal: ${event.message}`,
+			facts ? `Facts: ${facts}` : undefined,
+			"Hint: Inspect status, then nudge if the work seems stuck.",
+			childIntercomTarget
+				? `Nudge: ${nudgeCommand}`
+				: "Nudge: no child message route registered",
+			`Status: subagent({ action: "status", id: "${runTarget}" })`,
+			`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
+		].filter((line): line is string => Boolean(line)).join("\n");
+	}
+
+	return [
+		`Subagent needs attention: ${event.agent}`,
+		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+		`Signal: ${event.message}`,
+		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
+		"Hint: Inspect status first unless the run is clearly blocked.",
+		childIntercomTarget
+			? `Nudge: ${nudgeCommand}`
+			: "Nudge: no child message route registered",
+		`Status: subagent({ action: "status", id: "${runTarget}" })`,
+		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
+	].filter((line): line is string => Boolean(line)).join("\n");
+}
+
+export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	const statusLabel = event.reason === "completion_guard"
+		? "subagent failed"
+		: event.type === "active_long_running"
+			? "subagent active but long-running"
+			: "subagent needs attention";
+	return [
+		statusLabel,
+		"",
+		event.reason === "completion_guard"
+			? `${event.agent} failed in run ${event.runId}.`
+			: event.type === "active_long_running"
+				? `${event.agent} is still active but long-running in run ${event.runId}.`
+				: `${event.agent} needs attention in run ${event.runId}.`,
+		"",
+		formatControlNoticeMessage(event, childIntercomTarget),
+	].join("\n");
+}