@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -0,0 +1,201 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "../../shared/native-typebox.ts";
+import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.ts";
+import { setPromptSection } from "../../shared/prompt-sections.ts";
+import { loadConfig } from "../../extension/config.ts";
+import { registerChildExecutionCwd } from "./child-execution-cwd.ts";
+import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
+import type { JsonSchemaObject } from "../../shared/types.ts";
+import { SessionEntryCursor } from "../../shared/session-entries.ts";
+
+const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
+const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
+export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
+
+const STRUCTURED_OUTPUT_INSTRUCTIONS = [
+	"This subagent step has a strict structured output contract.",
+	"Your final action must be to call the `structured_output` tool with JSON matching the provided schema.",
+	"Do not rely on prose-only completion; if you do not call `structured_output`, the parent will fail this step.",
+].join("\n");
+
+export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
+	"You are a child subagent, not the parent orchestrator.",
+	"The parent session owns delegation, orchestration, review fanout, and follow-up worker launches.",
+	"Ignore prior parent-only orchestration instructions in inherited conversation history.",
+	"Do not propose or run subagents. Complete only your assigned role-specific task with the tools available to you.",
+	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+].join("\n");
+
+export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
+	"You are a child subagent with delegation enabled for your assigned task.",
+	"You may delegate useful helper work within that task when it saves time or improves quality, using the available delegation tools.",
+	"You remain responsible for your assigned result. The original parent owns integration, review synthesis, and final delivery.",
+	"Do not broaden the assigned scope or repeat approval requests for already-authorized work.",
+	"The native allowSubagents and maxSubagentDepth settings still apply.",
+	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+].join("\n");
+
+const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
+	"subagent-orchestration-instructions",
+	"subagent-slash-result",
+	"subagent-notify",
+	"subagent_control_notice",
+	"subagent-control",
+	"subagent-control-notice",
+]);
+const ORCHESTRATION_TOOLS = new Set(["subagent", "delegate", "agent_runs", "load_subagent"]);
+
+function readBooleanEnv(name: string): boolean | undefined {
+	const value = process.env[name];
+	if (value === undefined) return undefined;
+	return value !== "0";
+}
+
+function isParentOnlySubagentMessage(message: unknown): boolean {
+	const m = message as { role?: string; customType?: string };
+	return m?.role === "custom"
+		&& typeof m.customType === "string"
+		&& PARENT_ONLY_CUSTOM_MESSAGE_TYPES.has(m.customType);
+}
+
+function isSubagentExecutionResultMessage(message: unknown): boolean {
+	const m = message as { role?: string; toolName?: string };
+	return m?.role === "toolResult" && typeof m.toolName === "string" && ORCHESTRATION_TOOLS.has(m.toolName);
+}
+
+function isSubagentToolCallBlock(block: unknown): boolean {
+	const b = block as { type?: string; name?: string };
+	return b?.type === "toolCall" && typeof b.name === "string" && ORCHESTRATION_TOOLS.has(b.name);
+}
+
+function stripAssistantSubagentToolCallBlocks(message: unknown): unknown | undefined {
+	const m = message as { role?: string; content?: unknown };
+	if (m?.role !== "assistant" || !Array.isArray(m.content)) return message;
+	const filteredContent = m.content.filter((block) => !isSubagentToolCallBlock(block));
+	if (filteredContent.length === m.content.length) return message;
+	if (filteredContent.length === 0) return undefined;
+	return { ...m, content: filteredContent };
+}
+
+function stripParentOnlySubagentMessages<T>(messages: T[], fanoutChild = false): T[] {
+	let changed = false;
+	const filtered: T[] = [];
+	for (const message of messages) {
+		if (isParentOnlySubagentMessage(message) || (!fanoutChild && isSubagentExecutionResultMessage(message))) {
+			changed = true;
+			continue;
+		}
+		const stripped = fanoutChild ? message : stripAssistantSubagentToolCallBlocks(message);
+		if (stripped === undefined) {
+			changed = true;
+			continue;
+		}
+		if (stripped !== message) changed = true;
+		filtered.push(stripped as T);
+	}
+	return changed ? filtered : messages;
+}
+
+export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
+	registerChildExecutionCwd(pi);
+	// Print-mode observation uses the existing child runtime. turn_end follows native
+	// message append; message_end itself is deliberately never called a commit receipt.
+	let observedMessages = 0;
+	const cursor = new SessionEntryCursor();
+	let previousIds = new Set<string>();
+	pi.on("session_start", (_event, ctx) => {
+		cursor.reset();
+		observedMessages = 0;
+		const { entries } = cursor.read(ctx.sessionManager);
+		const baseline = process.env.PI_SUBAGENT_NATIVE_BASELINE_COUNT;
+		if (baseline && /^\d+$/.test(baseline)) process.stdout.write(`${JSON.stringify({ type: "subagent.native_baseline", sessionId: ctx.sessionManager.getSessionId(), entryIds: entries.slice(0, Number(baseline)).map((entry) => entry.id) })}\n`);
+		const file = ctx.sessionManager.getSessionFile();
+		previousIds = file && fs.existsSync(file) ? new Set(entries.map((entry) => entry.id)) : new Set();
+		if (!file || !fs.existsSync(file)) cursor.reset();
+	});
+	pi.on("message_end", (event) => { if (["assistant", "user", "toolResult"].includes(event.message.role)) observedMessages++; });
+	const observe = (ctx: import("@earendil-works/pi-coding-agent").ExtensionContext, boundary: string) => {
+		if (process.env.PI_SUBAGENT_CHILD !== "1") return;
+		const entries = [];
+		for (const entry of cursor.read(ctx.sessionManager).entries) if (!previousIds.has(entry.id)) {
+			previousIds.add(entry.id);
+			const message = entry.type === "message" ? entry.message : undefined;
+			entries.push({ id: entry.id, type: entry.type, parentId: entry.parentId,
+				...("checkpoint" in entry ? { checkpoint: entry.checkpoint } : {}),
+				...(entry.type === "usage" || entry.type === "compaction" || entry.type === "branch_summary" ? { usage: entry.usage } : {}),
+				...(entry.type === "usage" ? { provider: entry.provider, model: entry.model } : {}),
+				...(message ? { message: { role: message.role, timestamp: message.timestamp,
+					...("usage" in message ? { usage: message.usage } : {}),
+					...(message.role === "assistant" ? { provider: message.provider, model: message.model, responseModel: message.responseModel } : {}),
+					...("toolCallId" in message ? { toolCallId: message.toolCallId } : {}) } } : {}) });
+		}
+		const sessionFile = ctx.sessionManager.getSessionFile();
+		process.stdout.write(`${JSON.stringify({ type: "subagent.native", boundary, entries,
+			sessionId: ctx.sessionManager.getSessionId(), sessionFile, leafId: ctx.sessionManager.getLeafId(),
+			persisted: Boolean(sessionFile && fs.existsSync(sessionFile)), messageCount: observedMessages,
+			configuration: { ...(ctx.model ? { model: `${ctx.model.provider}/${ctx.model.id}` } : {}), thinking: pi.getThinkingLevel() } })}\n`);
+	};
+	pi.on("turn_end", (_event, ctx) => observe(ctx, "turn"));
+	pi.on("agent_settled", (_event, ctx) => observe(ctx, "settled"));
+	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
+	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
+	if (structuredOutputPath && structuredSchemaPath) {
+		const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8")) as JsonSchemaObject;
+		const parameters = Type.Object({ value: Type.Unsafe(schema) }, { additionalProperties: false });
+		pi.registerTool({
+			name: "structured_output",
+			label: "Structured Output",
+			description: "Submit the required final structured output for this subagent step. This terminates the step.",
+			parameters,
+			constrainedSampling: { type: "json_schema", strict: "prefer" },
+			async execute(_id: string, params: { value: unknown }) {
+				const validation = validateStructuredOutputValue(schema, params.value);
+				if (validation.status === "invalid") {
+					throw new Error(`Structured output validation failed: ${validation.message}`);
+				}
+				fs.mkdirSync(path.dirname(structuredOutputPath), { recursive: true });
+				fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 0o600 });
+				return {
+					content: [{ type: "text", text: "Structured output captured." }],
+					details: { path: structuredOutputPath },
+					terminate: true,
+				};
+			},
+		});
+		pi.on("session_start", () => {
+			pi.setActiveTools([...new Set([...pi.getActiveTools(), "structured_output"])]);
+		});
+	}
+
+	pi.on("context", (event) => {
+		// Filtering changes the provider prefix, never the saved journal. Fanout children
+		// need their own nested calls/results on later turns and resumes, so retain tool history.
+		const messages = stripParentOnlySubagentMessages(event.messages, readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV) === true);
+		if (messages === event.messages) return;
+		return { messages };
+	});
+
+	pi.on("before_agent_start", (event) => {
+		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
+		if (intercomSessionName && typeof pi.setSessionName === "function") {
+			pi.setSessionName(intercomSessionName);
+		}
+
+		const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
+		const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
+		const fanoutChild = readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV);
+		if (inheritProjectContext === undefined && inheritSkills === undefined && fanoutChild === undefined) return;
+		const options = event.systemPromptOptions;
+		// --no-skills/--no-context-files govern discovery. Keep explicitly selected
+		// skill bodies and context intact; never parse the rendered prompt to remove resources.
+		options.skills = options.skills.filter((skill) => skill.name !== "pi-subagents");
+		setPromptSection(options, "subagent_role", fanoutChild === true
+			? `${CHILD_FANOUT_BOUNDARY_INSTRUCTIONS}\n${loadConfig().compactChildTools === false
+				? "Use subagent({action:'list'}) to discover agents before delegation."
+				: "Use load_subagent({advanced:false}), then agent_runs({action:'profiles'}) to discover agents, delegate for ordinary work, and load_subagent for advanced workflows."}`
+			: CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS);
+		if (structuredOutputPath) setPromptSection(options, "subagent_output", STRUCTURED_OUTPUT_INSTRUCTIONS);
+	});
+}

package/src/runs/shared/subagent-tool-loop-guard.ts

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+
+const REPEATED_SUBAGENT_CALL_LIMIT = 5;
+const SUBAGENT_CALL_WINDOW_SIZE = REPEATED_SUBAGENT_CALL_LIMIT * 2 - 1;
+
+interface SubagentCallStart {
+	callKey: string;
+	toolName: unknown;
+	failed?: boolean;
+	toolCallId?: string;
+}
+
+export interface RepeatedSubagentCallGuardState {
+	recentStarts: boolean[];
+	recentSubagentCalls: SubagentCallStart[];
+}
+
+export function createRepeatedSubagentCallGuardState(): RepeatedSubagentCallGuardState {
+	return { recentStarts: [], recentSubagentCalls: [] };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stableStringify(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (!isRecord(value)) return JSON.stringify(value) ?? "undefined";
+	return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+}
+
+function subagentCallKey(toolName: unknown, args: unknown): string | undefined {
+	if ((toolName !== "subagent" && toolName !== "delegate" && toolName !== "agent_runs") || !isRecord(args)) return undefined;
+	try {
+		return createHash("sha256").update(`${toolName}:${stableStringify(args)}`).digest("hex");
+	} catch {
+		return undefined;
+	}
+}
+
+export function recordToolStartForSubagentLoopGuard(input: {
+	state: RepeatedSubagentCallGuardState;
+	toolCallId?: unknown;
+	toolName: unknown;
+	args: unknown;
+}): string | undefined {
+	const args = input.args;
+	const isList = isRecord(args) && (
+		input.toolName === "subagent" && args.action === "list"
+		|| input.toolName === "agent_runs" && args.action === "profiles"
+	);
+	input.state.recentStarts.push(isList);
+	if (input.state.recentStarts.length > SUBAGENT_CALL_WINDOW_SIZE) input.state.recentStarts.shift();
+	const callKey = subagentCallKey(input.toolName, input.args);
+	if (callKey) {
+		input.state.recentSubagentCalls.push({
+			callKey,
+			toolName: input.toolName,
+			toolCallId: typeof input.toolCallId === "string" ? input.toolCallId : undefined,
+		});
+		if (input.state.recentSubagentCalls.length > SUBAGENT_CALL_WINDOW_SIZE) input.state.recentSubagentCalls.shift();
+	}
+	if (!isList) return undefined;
+	const listCount = input.state.recentStarts.filter(Boolean).length;
+	if (listCount >= REPEATED_SUBAGENT_CALL_LIMIT) {
+		return `Child appears stuck repeating ${input.toolName}({ action: "${args.action}" }) ${listCount} times. Stopping to avoid a tool loop.`;
+	}
+	return undefined;
+}
+
+export function recordToolEndForSubagentLoopGuard(input: {
+	state: RepeatedSubagentCallGuardState;
+	toolCallId?: unknown;
+	toolName: unknown;
+	isError: unknown;
+}): string | undefined {
+	if (input.isError !== true) return undefined;
+	const toolCallId = typeof input.toolCallId === "string" ? input.toolCallId : undefined;
+	const entry = [...input.state.recentSubagentCalls].reverse().find((candidate) =>
+		candidate.toolName === input.toolName && candidate.failed === undefined
+		&& (!toolCallId || !candidate.toolCallId || candidate.toolCallId === toolCallId));
+	if (!entry) return undefined;
+	entry.failed = true;
+	const failedCount = input.state.recentSubagentCalls.filter((candidate) => candidate.failed && candidate.callKey === entry.callKey).length;
+	if (failedCount >= REPEATED_SUBAGENT_CALL_LIMIT) {
+		return `Child appears stuck repeating the same failed ${input.toolName} call ${failedCount} times. Stopping to avoid a tool loop.`;
+	}
+	return undefined;
+}

package/src/runs/shared/supervisor-questions.ts

@@ -0,0 +1,372 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { formatRunAction } from "../../shared/status-format.ts";
+import { NativeJournal, ownerProjection, readJsonProjection } from "../../shared/journal-reader.ts";
+import { getAgentDir } from "../../shared/utils.ts";
+import { runCooperatively, runSynchronously } from "../../shared/cooperative.ts";
+import { ASYNC_DIR, TEMP_ROOT_DIR, type AsyncStatus, type AsyncResultFile, type ResolvedAcceptanceConfig, type JsonSchemaObject, type OutputMode, type SavedLaunchConfig, type SingleResult, type AgentProgress } from "../../shared/types.ts";
+
+export const LEGACY_QUESTIONS_DIR = path.join(TEMP_ROOT_DIR, "supervisor-questions");
+export const QUESTIONS_DIR = path.join(getAgentDir(), "sessions", "subagent-runs");
+
+export interface SupervisorRunContract {
+	legacySource?: string;
+	recordVersion?: 3;
+	nativeSessionId?: string;
+	terminalLeafId?: string | null;
+	terminalEntryId?: string;
+	attemptBaseline?: string[];
+	baselineSource?: "native-migration";
+	effectiveConfiguration?: { model?: string; thinking?: string; modelRecordedAt?: number };
+	accounting?: { state: "complete" | "incomplete"; error?: string };
+	auditPath?: string;
+	task?: string;
+	label?: string;
+	result?: SingleResult;
+	effectiveAcceptance?: ResolvedAcceptanceConfig;
+	output?: string | false;
+	outputMode?: OutputMode;
+	outputSchema?: JsonSchemaObject;
+	launch?: SavedLaunchConfig;
+	/** Kept independently of progress, which is compacted away or stops streaming after detachment. */
+	modelSelection?: Pick<AgentProgress, "model" | "thinking" | "modelStartedAt">;
+	sessionFile?: string;
+	pid?: number;
+	processIdentity?: string;
+	updatedAt?: number;
+}
+
+export interface SupervisorQuestion extends SupervisorRunContract {
+	questionId: string;
+	runId: string;
+	ownerSessionId: string;
+	ownerTarget: string;
+	agent: string;
+	index: number;
+	childSessionId: string;
+	childTarget: string;
+	sessionFile: string;
+	cwd: string;
+	pid: number;
+	createdAt: number;
+	reason: "need_decision" | "interview_request";
+	message: string;
+	interview?: unknown;
+}
+
+export interface QuestionAnswer {
+	message: string;
+	answeredAt: number;
+	origin?: "human";
+}
+
+export interface QuestionDelivery {
+	kind: "live" | "revive";
+	runId: string;
+	deliveredAt: number;
+}
+
+export interface SupervisorQuestionView extends SupervisorQuestion {
+	state: "awaiting_input" | "answer_pending" | "answered" | "cancelled";
+	answer?: QuestionAnswer;
+	delivery?: QuestionDelivery;
+	revival?: { runId: string; pid: number; startedAt: number };
+}
+
+function safeId(value: string): string {
+	if (typeof value !== "string" || !/^[a-zA-Z0-9_-]+$/.test(value)) throw new Error("Invalid run or question ID.");
+	return value;
+}
+
+export function getRunMetadataDir(runId: string, root = QUESTIONS_DIR): string {
+	return path.join(root, safeId(runId));
+}
+
+export function saveAsyncRunResult(runId: string, result: AsyncResultFile): AsyncResultFile {
+	const file = path.join(getRunMetadataDir(runId), "result.json");
+	const previous = readRunJson<AsyncResultFile>(file);
+	if (previous?.completionId && result.completionId && previous.completionId !== result.completionId) throw new Error("Conflicting completion identity");
+	const saved = { ...result, recordVersion: 3 as const, completionId: previous?.completionId ?? result.completionId ?? randomUUID(),
+		...(preserveLegacyOwner(file, previous) ? { legacySource: `${file}.legacy` } : {}),
+		results: result.results?.map((child, index) => compactOwnerResult(runId, index, child)) };
+	writeAtomicJson(file, saved);
+	return saved;
+}
+
+function preserveLegacyOwner(file: string, previous: { recordVersion?: number } | undefined): boolean {
+	if (!previous || previous.recordVersion === 3) return false;
+	try { fs.copyFileSync(file, `${file}.legacy`, fs.constants.COPYFILE_EXCL); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+	return true;
+}
+
+export function compactOwnerResult<T extends { finalOutput?: string; output?: string; initialOutput?: string; initialOutputPath?: string; messages?: unknown; artifactPaths?: { outputPath?: string }; fullOutputPath?: string }>(runId: string, index: number, result: T, root = QUESTIONS_DIR): T {
+	const output = result.finalOutput ?? result.output;
+	let fullOutputPath = result.fullOutputPath;
+	if (output && output.length > 8192) {
+		fullOutputPath ??= result.artifactPaths?.outputPath;
+		if (!fullOutputPath) {
+			fullOutputPath = path.join(getRunMetadataDir(runId, root), "outputs", `${index}.txt`);
+			fs.mkdirSync(path.dirname(fullOutputPath), { recursive: true });
+			fs.writeFileSync(fullOutputPath, output, { mode: 0o600 });
+		}
+	}
+	let initialOutputPath = result.initialOutputPath;
+	if (result.initialOutput && result.initialOutput.length > 8192 && !initialOutputPath) {
+		initialOutputPath = path.join(getRunMetadataDir(runId, root), "outputs", `${index}.initial.txt`);
+		fs.mkdirSync(path.dirname(initialOutputPath), { recursive: true });
+		fs.writeFileSync(initialOutputPath, result.initialOutput, { mode: 0o600 });
+	}
+	return { ...result, messages: undefined, ...(fullOutputPath ? { fullOutputPath } : {}),
+		...(initialOutputPath ? { initialOutputPath } : {}),
+		...(result.finalOutput !== undefined ? { finalOutput: result.finalOutput.slice(-8192) } : {}),
+		...(result.output !== undefined ? { output: result.output.slice(-8192) } : {}),
+		...(result.initialOutput !== undefined ? { initialOutput: result.initialOutput.slice(-8192) } : {}) };
+}
+
+export function saveRunStatus(runId: string, status: AsyncStatus): void {
+	writeAtomicJson(path.join(getRunMetadataDir(runId), "status.json"), status);
+}
+
+export function readRunJson<T>(file: string): T | undefined {
+	try {
+		return readJsonProjection(file, ownerProjection) as T;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function questionDir(question: Pick<SupervisorQuestion, "runId" | "questionId">, root = QUESTIONS_DIR): string {
+	return path.join(root, safeId(question.runId), "questions", safeId(question.questionId));
+}
+
+// Atomic publication without replacement: concurrent answers/launches have exactly one winner.
+function writeOnce(file: string, value: object): boolean {
+	const temporary = `${file}.${randomUUID()}.tmp`;
+	writeAtomicJson(temporary, value);
+	try {
+		fs.linkSync(temporary, file);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+		throw error;
+	} finally {
+		fs.rmSync(temporary, { force: true });
+	}
+}
+
+export function saveQuestionOwner(runId: string, sessionId: string, root = QUESTIONS_DIR): void {
+	writeAtomicJson(path.join(root, safeId(runId), "question-owner.json"), { sessionId });
+}
+
+export function saveQuestionContract(runId: string, index: number, contract: SupervisorRunContract, root = QUESTIONS_DIR): void {
+	if (!Number.isSafeInteger(index) || index < 0) throw new Error("Child index must be a non-negative integer.");
+	const file = path.join(root, safeId(runId), "contracts", `${index}.json`);
+	const previous = readRunJson<SupervisorRunContract>(file);
+	writeAtomicJson(file, { ...previous, ...contract, recordVersion: 3,
+		...(preserveLegacyOwner(file, previous) ? { legacySource: `${file}.legacy` } : {}),
+		...(previous?.attemptBaseline && contract.baselineSource !== "native-migration" ? { attemptBaseline: previous.attemptBaseline } : {}),
+		...(contract.result ? { result: compactOwnerResult(runId, index, contract.result, root) } : {}),
+		...(previous?.launch ? { launch: previous.launch } : {}) });
+}
+
+export function readQuestionContract(runId: string, index: number, root = QUESTIONS_DIR, projection: { sessionFile?: string; endedAt?: number; readConfiguration?: false } = {}): SupervisorRunContract | undefined {
+	const contract = readRunJson<SupervisorRunContract>(path.join(root, safeId(runId), "contracts", `${index}.json`));
+	if (!contract?.launch || projection.readConfiguration === false) return contract;
+	const sessionFile = projection.sessionFile ?? contract.sessionFile;
+	if (contract.recordVersion !== 3 && !contract.effectiveConfiguration && sessionFile && fs.existsSync(sessionFile) && !contract.launch.model?.startsWith("claude-code/")) {
+		// One-time read-only native recovery. Subsequent controls use the compact
+		// selection, and the frozen requested profile is never rewritten.
+		const journal = new NativeJournal(sessionFile, "inspect", true);
+		contract.effectiveConfiguration = journal.configuration(projection.endedAt, contract.terminalLeafId);
+		saveQuestionContract(runId, index, { effectiveConfiguration: contract.effectiveConfiguration }, root);
+	}
+	const native = contract.effectiveConfiguration ?? {};
+	return { ...contract, launch: { ...contract.launch, ...native } };
+}
+
+export function migrateSupervisorQuestions(ownerSessionId: string, runId?: string): void {
+	runSynchronously(migrateSupervisorQuestionSteps(ownerSessionId, runId));
+}
+
+export function* migrateSupervisorQuestionSteps(ownerSessionId: string, runId?: string): Generator<void> {
+	if (!fs.existsSync(LEGACY_QUESTIONS_DIR)) return;
+	const runs = runId === undefined ? fs.readdirSync(LEGACY_QUESTIONS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : [safeId(runId)];
+	for (const id of runs) {
+		yield;
+		try {
+			const source = getRunMetadataDir(id, LEGACY_QUESTIONS_DIR);
+			const owner = readRunJson<{ sessionId?: string }>(path.join(source, "question-owner.json"));
+			if (owner?.sessionId !== ownerSessionId) continue;
+			fs.cpSync(source, getRunMetadataDir(id), { recursive: true, force: false });
+		} catch (error) {
+			if (runId !== undefined) throw error;
+			console.error(`Could not recover legacy questions for ${id}: ${String(error)}`);
+		}
+	}
+}
+
+export function createSupervisorQuestion(input: Omit<SupervisorQuestion, "questionId" | "createdAt" | "ownerSessionId">, root = QUESTIONS_DIR): SupervisorQuestion {
+	const runDir = path.join(root, safeId(input.runId));
+	const status = readRunJson<AsyncStatus>(path.join(runDir, "status.json"))
+		?? (root === QUESTIONS_DIR ? readRunJson<AsyncStatus>(path.join(ASYNC_DIR, safeId(input.runId), "status.json")) : undefined);
+	const owner = readRunJson<{ sessionId: string }>(path.join(runDir, "question-owner.json")) ?? status;
+	if (!owner?.sessionId) throw new Error(`Run ${input.runId} has no saved question owner; cannot create a recoverable supervisor question.`);
+	if (!input.sessionFile || path.extname(input.sessionFile) !== ".jsonl") throw new Error("Supervisor questions require a saved child session.");
+	if (!Number.isSafeInteger(input.index) || input.index < 0) throw new Error("Child index must be a non-negative integer.");
+	if (!input.message.trim()) throw new Error("Supervisor question must not be empty.");
+	const contract = readQuestionContract(input.runId, input.index, root, { sessionFile: input.sessionFile })
+		?? { effectiveAcceptance: status?.steps?.[input.index]?.acceptance?.effectiveAcceptance };
+	const question = { ...input, ...contract, sessionFile: input.sessionFile, pid: input.pid, ownerSessionId: owner.sessionId, questionId: randomUUID(), createdAt: Date.now() };
+	writeAtomicJson(path.join(questionDir(question, root), "question.json"), question);
+	return question;
+}
+
+function questionStatePaths(question: SupervisorQuestion, file: string, root: string): string[] {
+	const current = path.join(questionDir(question, root), file);
+	const legacy = questionDir(question, LEGACY_QUESTIONS_DIR);
+	// Old waiters still claim the legacy file; both runtimes must compete on that same inode.
+	return root === QUESTIONS_DIR && fs.existsSync(path.join(legacy, "question.json")) ? [path.join(legacy, file), current] : [current];
+}
+
+function writeQuestionStateOnce(question: SupervisorQuestion, file: string, value: object, root: string): boolean {
+	const [primary, ...mirrors] = questionStatePaths(question, file, root);
+	const written = writeOnce(primary!, value);
+	const winner = written ? value : readRunJson<object>(primary!)!;
+	for (const target of mirrors) writeOnce(target, winner);
+	return written;
+}
+
+export function readQuestionState(question: SupervisorQuestion, root = QUESTIONS_DIR): SupervisorQuestionView {
+	const read = <T>(file: string): T | undefined => questionStatePaths(question, file, root).map((entry) => readRunJson<T>(entry)).find((entry) => entry !== undefined);
+	const answer = read<QuestionAnswer>("answer.json");
+	const delivery = read<QuestionDelivery>("delivery.json");
+	const cancelled = read("cancelled.json") !== undefined;
+	const revival = read<SupervisorQuestionView["revival"]>("revival.json");
+	return { ...question, state: delivery ? "answered" : cancelled ? "cancelled" : answer ? "answer_pending" : "awaiting_input", ...(answer ? { answer } : {}), ...(delivery ? { delivery } : {}), ...(revival ? { revival } : {}) };
+}
+
+export function listRunQuestions(runDir: string): SupervisorQuestionView[] {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(path.join(runDir, "questions"), { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	return entries.filter((entry) => entry.isDirectory()).flatMap((entry) => {
+		const question = readRunJson<SupervisorQuestion>(path.join(runDir, "questions", entry.name, "question.json"));
+		return question ? [readQuestionState(question, path.dirname(runDir))] : [];
+	});
+}
+
+/** Known run IDs need neither a global directory walk nor prefix resolution. */
+export function listOwnedRunQuestions(ownerSessionId: string, runId: string): SupervisorQuestionView[] {
+	migrateSupervisorQuestions(ownerSessionId, runId);
+	return listRunQuestions(getRunMetadataDir(runId)).filter((question) => question.ownerSessionId === ownerSessionId);
+}
+
+export function pendingSupervisorQuestion(input: { runId: string; agent: string; index: number; sessionFile?: string; pid?: number }): import("../../shared/types.ts").ControlEvent["supervisorQuestion"] {
+	if (!input.sessionFile) return undefined;
+	try {
+		const pid = input.pid ?? readQuestionContract(input.runId, input.index)?.pid;
+		const question = listRunQuestions(getRunMetadataDir(input.runId)).find((question) =>
+			question.runId === input.runId && question.agent === input.agent && question.index === input.index
+			&& question.sessionFile === input.sessionFile && question.pid === pid
+			&& (question.state === "awaiting_input" || question.state === "answer_pending"));
+		if (question && (question.state === "awaiting_input" || question.state === "answer_pending")) return {
+			questionId: question.questionId, state: question.state, ...(question.answer ? { answer: question.answer.message } : {}),
+		};
+	} catch (error) {
+		console.error(`Could not read supervisor wait for ${input.runId}:${input.index}:`, error);
+	}
+	return undefined;
+}
+
+export function listSupervisorQuestions(ownerSessionId: string, runId?: string, root = QUESTIONS_DIR): SupervisorQuestionView[] {
+	return runSynchronously(supervisorQuestionSteps(ownerSessionId, runId, root));
+}
+
+export function listSupervisorQuestionsAsync(ownerSessionId: string): Promise<SupervisorQuestionView[]> {
+	return runCooperatively(supervisorQuestionSteps(ownerSessionId));
+}
+
+function* supervisorQuestionSteps(ownerSessionId: string, runId?: string, root = QUESTIONS_DIR): Generator<void, SupervisorQuestionView[]> {
+	if (runId !== undefined) safeId(runId);
+	if (root === QUESTIONS_DIR) yield* migrateSupervisorQuestionSteps(ownerSessionId);
+	if (!fs.existsSync(root)) return [];
+	const runs = fs.readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && (!runId || entry.name.startsWith(runId)));
+	const questions: SupervisorQuestionView[] = [];
+	for (const entry of runs) {
+		yield;
+		try { questions.push(...listRunQuestions(path.join(root, entry.name)).filter((question) => question.ownerSessionId === ownerSessionId)); }
+		catch (error) {
+			if (runId !== undefined) throw error;
+			console.error(`Could not list questions for ${entry.name}: ${String(error)}`);
+		}
+	}
+	if (runId && new Set(questions.map((question) => question.runId)).size > 1) throw new Error(`Ambiguous run ID prefix '${runId}'.`);
+	return questions.sort((a, b) => a.createdAt - b.createdAt);
+}
+
+export function saveQuestionAnswer(question: SupervisorQuestion, message: string, root = QUESTIONS_DIR, origin?: "human"): QuestionAnswer {
+	if (typeof message !== "string" || !message.trim()) throw new Error("action='answer' requires a non-empty message.");
+	const state = readQuestionState(question, root);
+	if (state.state === "cancelled") throw new Error(`Question ${question.questionId} was cancelled. Use continue for a new follow-up.`);
+	const answer: QuestionAnswer = { message: message.trim(), answeredAt: state.answer?.answeredAt ?? Date.now(), ...(state.answer?.origin ?? origin ? { origin: state.answer?.origin ?? origin } : {}) };
+	if (state.answer && state.answer.message !== answer.message) throw new Error(`Question ${question.questionId} already has a different saved answer. The original answer was retained.`);
+	if (writeQuestionStateOnce(question, "answer.json", answer, root)) return answer;
+	const existing = readQuestionState(question, root).answer!;
+	if (existing.message !== answer.message) throw new Error(`Question ${question.questionId} already has a different saved answer. The original answer was retained.`);
+	return existing;
+}
+
+export function recordQuestionDelivery(question: SupervisorQuestion, delivery: QuestionDelivery, root = QUESTIONS_DIR): void {
+	writeQuestionStateOnce(question, "delivery.json", delivery, root);
+}
+
+export function cancelSupervisorQuestion(question: SupervisorQuestion, root = QUESTIONS_DIR): void {
+	writeQuestionStateOnce(question, "cancelled.json", { cancelledAt: Date.now() }, root);
+}
+
+export function questionProcessAlive(question: Pick<SupervisorQuestion, "pid">): boolean {
+	if (!Number.isSafeInteger(question.pid) || question.pid <= 0) throw new Error("Invalid child process ID.");
+	try {
+		process.kill(question.pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+export function claimQuestionRevival(question: SupervisorQuestion, root = QUESTIONS_DIR): { claimed: boolean; runId: string } {
+	const runId = `answer-${question.questionId}`;
+	if (readQuestionState(question, root).revival) return { claimed: false, runId };
+	return { claimed: writeQuestionStateOnce(question, "revival.json", { runId, pid: process.pid, startedAt: Date.now() }, root), runId };
+}
+
+export function releaseQuestionRevival(question: SupervisorQuestion, root = QUESTIONS_DIR): void {
+	for (const file of questionStatePaths(question, "revival.json", root)) fs.rmSync(file, { force: true });
+}
+
+export function questionRecoveryHint(question: SupervisorQuestion, childSafe = false): string {
+	return `Recover an unlaunched continuation: ${formatRunAction("resume", question.runId, { index: question.index, message: "Continue with the saved supervisor answer." }, childSafe)}`;
+}
+
+export function formatSupervisorQuestions(questions: SupervisorQuestionView[], childSafe = false): string {
+	if (!questions.length) return "No supervisor questions owned by this session.";
+	return questions.map((question) => [
+		`Question: ${question.questionId} | ${question.state}`,
+		`Run: ${question.runId} | Child: ${question.index} (${question.agent}) | Owner: ${question.ownerSessionId}`,
+		`Session: ${question.sessionFile} | Child target: ${question.childTarget}`,
+		question.message,
+		...(question.answer ? [`Saved answer: ${question.answer.message}`] : []),
+		...(question.revival && !question.delivery ? [`Continuation requested: ${question.revival.runId}; delivery unconfirmed. Answer retained.`, questionRecoveryHint(question, childSafe)] : []),
+		question.delivery ? `Answer delivered via ${question.delivery.kind}; run: ${question.delivery.runId}`
+			: question.state === "cancelled" ? "Question cancelled; use continue for a new follow-up."
+			: `Answer: ${formatRunAction("answer", question.runId, { questionId: question.questionId, message: question.answer?.message ?? "..." }, childSafe)}`,
+	].join("\n")).join("\n\n");
+}