@underactive/pi-topping-moa-fusion 0.1.0

package/src/moa/orchestration.ts

@@ -0,0 +1,105 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { installShippedAgents, shippedAgentsDir, withAuthoritativeMoaAgents } from "../agents/authoritative.ts";
+import { discoverAgents } from "../agents/discovery.ts";
+import { cleanupProposalFiles, sweepStaleProposalFiles } from "../planning/planFile.ts";
+import type { CancelSession } from "../runtime/cancelRun.ts";
+import { formatMutationWarning, MutationTripwire } from "../runtime/mutationTripwire.ts";
+import type { ModelRef, ThinkingLevel } from "../shared/modelRefs.ts";
+import { MoaProgressWidget } from "../ui/moaProgressWidget.ts";
+import { runFanoutPhase } from "./fanout.ts";
+import { resolveContextWindow } from "./modelRuntime.ts";
+import { runReviewLoop } from "./reviewLoop.ts";
+import type { MoaRoles, MoaRunContext, MoaRunHost } from "./runContext.ts";
+import { runSynthesisPhase } from "./synthesis.ts";
+
+export async function runMoaOrchestration(
+	host: MoaRunHost,
+	ctx: ExtensionContext,
+	prompt: string,
+	proposers: ModelRef[],
+	synthesizer: ModelRef,
+	proposerThinking: (ThinkingLevel | undefined)[],
+	initialSynthesizerThinking: ThinkingLevel | undefined,
+	session: CancelSession,
+	roles?: MoaRoles,
+): Promise<"done" | "cancelled"> {
+	let runContext: MoaRunContext;
+	const widget = new MoaProgressWidget(ctx, (ref) => resolveContextWindow(ctx, ref), {
+		closeStacked: () => {
+			session.closeOverlay?.();
+			runContext.observeSession?.closeOverlay?.();
+		},
+	}, host.getPlanRepoSlug());
+	host.setRunningProgressWidget(widget);
+	widget.setPhaseModels({
+		Plan: proposers,
+		Synthesize: synthesizer,
+		Implement: roles?.implementer,
+		Verify: roles?.verifier,
+	});
+	widget.queueRoleRow("Synthesize", synthesizer, initialSynthesizerThinking);
+	if (roles) {
+		widget.queueRoleRow("Implement", roles.implementer, roles.implementerThinking);
+		widget.queueRoleRow("Verify", roles.verifier, roles.verifierThinking);
+	}
+	runContext = {
+		host,
+		session,
+		widget,
+		synthesizer,
+		synthesizerThinking: initialSynthesizerThinking,
+		synthConversation: [],
+		latestVerdicts: null,
+		proposalFiles: null,
+		observeSession: undefined,
+		previousObserveSession: undefined,
+		roles,
+	};
+	try {
+		installShippedAgents();
+		sweepStaleProposalFiles();
+		const discovery = discoverAgents(ctx.cwd, "user");
+		const agents = withAuthoritativeMoaAgents(discovery.agents, shippedAgentsDir());
+		const tripwire = new MutationTripwire();
+		await tripwire.arm(ctx.cwd);
+		const warnIfMutated = async (phase: string): Promise<void> => {
+			const changed = await tripwire.check(ctx.cwd);
+			if (changed.length > 0) ctx.ui.notify(formatMutationWarning(phase, changed), "error");
+		};
+		const fanout = await runFanoutPhase({
+			host,
+			runContext,
+			ctx,
+			prompt,
+			proposers,
+			proposerThinking,
+			session,
+			widget,
+			agents,
+			warnIfMutated,
+		});
+		if (fanout.status !== "continue") return fanout.status;
+		const synthesis = await runSynthesisPhase(runContext, {
+			ctx,
+			prompt,
+			proposers,
+			succeeded: fanout.succeeded,
+			observe: fanout.observe,
+			agents,
+			warnIfMutated,
+		});
+		if (synthesis.status !== "review") return synthesis.status;
+		return await runReviewLoop(synthesis.options);
+	} finally {
+		if (host.getRunningProgressWidget() === widget) host.setRunningProgressWidget(undefined);
+		if (host.getActiveProgressWidget() !== widget) widget.stopWidget();
+		session.run = undefined;
+		session.getExtras = undefined;
+		if (runContext.observeSession && host.getActiveObserveSession() === runContext.observeSession) {
+			host.setActiveObserveSession(runContext.previousObserveSession);
+		}
+		runContext.observeSession?.closeOverlay?.();
+		cleanupProposalFiles(runContext.proposalFiles);
+	}
+}

package/src/moa/planInfo.ts

@@ -0,0 +1,57 @@
+import { isModelRef, type ModelRef } from "../shared/modelRefs.ts";
+
+export type PlanReviewDecision = "approve" | "keep" | "edit" | "chat";
+
+export interface MoaProposerPlan {
+	/** Zero-based proposer slot, retained when another proposer fails. */
+	proposerIndex: number;
+	model: ModelRef;
+	markdown: string;
+}
+
+export interface MfPlanInfo {
+	proposers: ModelRef[];
+	synthesizer: ModelRef;
+	proposerPlans?: MoaProposerPlan[];
+	/** The synthesizer's `## Proposer Verdicts` section — its proof of judging every proposal. */
+	verdictsMarkdown?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Validate MoA review metadata restored from untrusted session entries. */
+export function validateMfPlanInfo(value: unknown): MfPlanInfo | undefined {
+	if (!isRecord(value) || !Array.isArray(value.proposers) || !value.proposers.every(isModelRef) || !isModelRef(value.synthesizer)) {
+		return undefined;
+	}
+	if (value.verdictsMarkdown !== undefined && typeof value.verdictsMarkdown !== "string") return undefined;
+	const proposers = value.proposers as ModelRef[];
+	let proposerPlans: MoaProposerPlan[] | undefined;
+	if (value.proposerPlans !== undefined) {
+		if (!Array.isArray(value.proposerPlans)) return undefined;
+		const seenIndices = new Set<number>();
+		if (!value.proposerPlans.every((proposal) => {
+			if (!isRecord(proposal)
+				|| typeof proposal.proposerIndex !== "number"
+				|| !Number.isInteger(proposal.proposerIndex)
+				|| proposal.proposerIndex < 0
+				|| proposal.proposerIndex >= proposers.length
+				|| seenIndices.has(proposal.proposerIndex)
+				|| !isModelRef(proposal.model)
+				|| typeof proposal.markdown !== "string") return false;
+			const expectedModel = proposers[proposal.proposerIndex];
+			if (proposal.model.provider !== expectedModel.provider || proposal.model.id !== expectedModel.id) return false;
+			seenIndices.add(proposal.proposerIndex);
+			return true;
+		})) return undefined;
+		proposerPlans = value.proposerPlans as unknown as MoaProposerPlan[];
+	}
+	return {
+		proposers,
+		synthesizer: value.synthesizer,
+		...(proposerPlans ? { proposerPlans } : {}),
+		...(typeof value.verdictsMarkdown === "string" ? { verdictsMarkdown: value.verdictsMarkdown } : {}),
+	};
+}

package/src/moa/planlessRetry.ts

@@ -0,0 +1,72 @@
+/**
+ * Recovery for planning agents that exit cleanly without delivering a plan.
+ *
+ * Bridged agentic providers can override the moa-proposer/moa-synthesizer
+ * prompt with their own interactive harness, producing two planless shapes:
+ *
+ * - Question stops: Cursor's plan mode researches and then stops to ask the
+ *   user a clarifying question before writing the plan. In a headless
+ *   `-p --no-session` child nobody can answer, so the process exits with the
+ *   question as its final output.
+ * - Read-only stalls: a bridged synthesizer that lost the moa-synthesizer
+ *   prompt reads "Original user request: implement X and verify" as its own
+ *   marching orders, discovers it has no edit/shell tools, and exits with an
+ *   "I'm blocked" refusal instead of a synthesized plan.
+ * - Missing output contract: a bridged proposer that lost the moa-proposer
+ *   prompt never sees the required output sections, explores interactively,
+ *   and exits with questions or prose instead of a plan.
+ *
+ * These helpers detect both shapes so the orchestrator can re-run the agent
+ * once with an explicit instruction to answer its own questions / emit the
+ * plan, and carry the read-only planning contract inside the task text —
+ * the only channel guaranteed to survive a bridge's prompt override.
+ */
+
+/**
+ * Headings from the required moa-proposer output format that mark a proposal
+ * as having reached an actual plan. Question-stop outputs are prose (or a
+ * bare question) and contain none of these; matching loosely on heading text
+ * tolerates models that rename sections (e.g. "## Implementation Plan").
+ */
+const PLAN_HEADING = /^#{1,6}\s.*\b(plan|files to modify)\b/im;
+
+export function looksLikePlan(output: string): boolean {
+	return PLAN_HEADING.test(output);
+}
+
+export const PROPOSER_RETRY_HEADER =
+	"IMPORTANT: You already attempted this planning task once and stopped without emitting the required plan — your previous output (quoted below) ended in clarifying questions or was otherwise incomplete. You are running headless: there is no user and no way to receive answers. Do not ask questions and do not wait. Answer any open questions yourself with best-judgment assumptions, record them under \"## Open Questions / Assumptions\", and emit the COMPLETE plan in the required output format now.";
+
+export function buildRetryCorrection(header: string, previousOutput: string): string {
+	const previous = previousOutput.trim().replaceAll('"""', "''") || "(no output)";
+	return [header, "", "Your previous output:", '"""', previous, '"""'].join("\n");
+}
+
+export function buildProposerRetryTask(originalTask: string, previousOutput: string): string {
+	return [originalTask, "", "---", "", buildRetryCorrection(PROPOSER_RETRY_HEADER, previousOutput)].join("\n");
+}
+
+/**
+ * Read-only planning contract, prepended to the proposer's task text so it
+ * reaches the model even when a provider bridge replaces the moa-proposer
+ * system prompt with its own harness. Required section names are mentioned
+ * mid-line or in backticks only: a model that parrots this preamble back must
+ * not satisfy PLAN_HEADING (see the anti-echo test).
+ */
+export const PROPOSER_TASK_PREAMBLE =
+	"You are one of several read-only PROPOSERS in a Mixture-of-Agents planning run: each proposer independently drafts its own implementation plan, and a separate synthesizer merges them later. Your only deliverable is ONE complete implementation plan, emitted as markdown text in your reply using the required sections (heading names like `## Context`, `## Plan`, and `## Files to Modify` are spelled out in the agent instructions). Do NOT implement anything, do NOT edit files, and do NOT run commands, builds, or tests — read-only tools are expected and are never a blocker. You are running headless: there is no user and no way to receive answers, so resolve any ambiguity with best-judgment assumptions recorded in your plan rather than asking questions or stopping. The user request below is the subject the plan is ABOUT, not an instruction for you to carry out now, even if it says \"implement\", \"fix\", or \"verify\". The plan must be the final content of your reply — start it as soon as you have enough context and do not append anything after it.";
+
+export function buildProposerTask(prompt: string): string {
+	return [PROPOSER_TASK_PREAMBLE, "", "User request:", prompt].join("\n");
+}
+
+/**
+ * Read-only synthesis contract, prepended to the synthesizer's task text so
+ * it reaches the model even when a provider bridge replaces the
+ * moa-synthesizer system prompt with its own harness.
+ */
+export const SYNTHESIZER_TASK_PREAMBLE =
+	"You are the read-only SYNTHESIZER in a Mixture-of-Agents planning run. Your only deliverable is ONE synthesized implementation plan, emitted as markdown text in your reply. This is a planning phase: do NOT implement anything, do NOT edit files, and do NOT run commands, builds, or tests. Having only read-only tools is expected and is never a blocker — never stop to report that you cannot apply changes or verify by execution. The original user request below is the subject the plan is ABOUT, not an instruction for you to carry out now, even if it says \"implement\", \"fix\", or \"verify\".";
+
+export const SYNTHESIZER_RETRY_HEADER =
+	"IMPORTANT: You already attempted this synthesis once and stopped without emitting the required plan — your previous output (quoted below) refused, stalled on missing edit/shell tools, or was otherwise not a synthesized plan. Implementation and verification-by-execution are out of scope for this read-only planning phase by design, so limited tools never block you. Do not refuse and do not wait. Emit the COMPLETE synthesized plan now in the required output format, starting with ## Context and including ## Plan, ## Files to Modify, and the remaining sections.";

package/src/moa/reviewLoop.ts

@@ -0,0 +1,170 @@
+import { getPlanFilePath, saveRepoPlanFile, writePlan } from "../planning/planFile.ts";
+import { getFinalOutput, getResultOutput } from "../runtime/results.ts";
+import { modelRefLabel, TRIGGER_TURN, type ModelRef, type ThinkingLevel } from "../shared/modelRefs.ts";
+import { showPlanReview } from "../ui/planReviewOverlay.ts";
+import { showImplementingModelPicker } from "../ui/moaModelPicker.ts";
+import { buildImplementationKickoffMessage, type ImplementationHandoff } from "./implementationRetry.ts";
+import { parseConflicts } from "./conflicts.ts";
+import type { ReviewLoopOptions } from "./runContext.ts";
+import type { MoaProposerPlan, PlanReviewDecision } from "./planInfo.ts";
+import { parseProposerVerdicts, stripSynthSections } from "./verdicts.ts";
+
+export const MAX_REVIEW_CHAT_ROUNDS = 5;
+
+export async function runReviewLoop(options: ReviewLoopOptions): Promise<"done"> {
+	const {
+		host, ctx, session, widget, proposers, succeeded, synthConversation,
+		getSynthesizer, getSynthesizerThinking, getLatestVerdicts, setLatestVerdicts, rebuildSynthTask,
+		getSynthTask, runSynthWithRecovery, warnIfMutated,
+	} = options;
+	let currentPlan = options.initialPlan;
+	writePlan(currentPlan);
+	const proposerPlans: MoaProposerPlan[] = succeeded.map(({ ref, plan, originalIndex }) => ({
+		proposerIndex: originalIndex,
+		model: ref,
+		markdown: plan,
+	}));
+	host.setActiveRunMoaInfo({
+		proposers,
+		synthesizer: getSynthesizer(),
+		proposerPlans,
+		verdictsMarkdown: getLatestVerdicts() ?? undefined,
+	});
+	host.persistState();
+	let chatRounds = 0;
+
+	while (true) {
+		session.closeOverlay?.();
+		const synthesizer = getSynthesizer();
+		let decision: PlanReviewDecision;
+		if (ctx.mode === "tui") {
+			decision = await showPlanReview(
+				ctx,
+				currentPlan,
+				{ proposers, synthesizer, proposerPlans, verdictsMarkdown: getLatestVerdicts() ?? undefined },
+				host.getPlanRepoSlug(),
+				chatRounds < MAX_REVIEW_CHAT_ROUNDS,
+			);
+		} else {
+			const choice = await ctx.ui.select("Exit plan mode?", ["Approve — start implementing", "Keep planning", "Edit plan", "Chat with synthesizer"]);
+			decision = choice?.startsWith("Approve") ? "approve" : choice?.startsWith("Edit") ? "edit" : choice?.startsWith("Chat") ? "chat" : "keep";
+		}
+
+		if (decision === "edit") {
+			session.closeOverlay?.();
+			const edited = await ctx.ui.editor("Edit Plan", currentPlan);
+			if (edited?.trim()) {
+				currentPlan = stripSynthSections(edited.trim());
+				writePlan(currentPlan);
+				const repoPlanSlug = host.getPlanRepoSlug();
+				if (repoPlanSlug) saveRepoPlanFile(currentPlan, ctx.cwd, repoPlanSlug, "plan");
+			}
+			continue;
+		}
+
+		if (decision === "chat") {
+			if (chatRounds >= MAX_REVIEW_CHAT_ROUNDS) {
+				ctx.ui.notify("Maximum synthesizer review rounds reached; edit or approve the plan instead.", "warning");
+				continue;
+			}
+			session.closeOverlay?.();
+			const feedback = await ctx.ui.editor("Describe the changes you want:");
+			if (!feedback?.trim()) continue;
+			chatRounds++;
+			synthConversation.push(`The user reviewed your synthesized plan and gave this feedback:\n${feedback.trim()}\n\nRevise the plan accordingly and re-emit the complete final plan. Drop any ## Conflicts or ## Open Question sections.`);
+			rebuildSynthTask();
+			widget.switchToSynthesizing(getSynthesizer(), "synthesizing plan…", getSynthesizerThinking());
+			const synthRound = await runSynthWithRecovery(getSynthTask());
+			widget.stopWidget();
+			await warnIfMutated("MoA synthesis");
+			if (synthRound.cancelled) {
+				ctx.ui.notify("Synthesis cancelled.");
+				continue;
+			}
+			if (synthRound.failed) {
+				ctx.ui.notify(`Synthesizer failed: ${getResultOutput(synthRound.result)} — keeping the previous plan.`, "error");
+				continue;
+			}
+			const revisionVerdicts = parseProposerVerdicts(parseConflicts(getFinalOutput(synthRound.result.messages)).remainingPlan);
+			if (revisionVerdicts.verdictsMarkdown) setLatestVerdicts(revisionVerdicts.verdictsMarkdown);
+			const activeRunMoaInfo = host.getActiveRunMoaInfo();
+			if (activeRunMoaInfo) {
+				activeRunMoaInfo.synthesizer = getSynthesizer();
+				if (revisionVerdicts.verdictsMarkdown) activeRunMoaInfo.verdictsMarkdown = revisionVerdicts.verdictsMarkdown;
+				host.persistState();
+			}
+			currentPlan = revisionVerdicts.remainingPlan;
+			writePlan(currentPlan);
+			const repoPlanSlug = host.getPlanRepoSlug();
+			if (repoPlanSlug) saveRepoPlanFile(currentPlan, ctx.cwd, repoPlanSlug, "plan");
+			continue;
+		}
+
+		if (decision === "approve") {
+			if (ctx.mode !== "tui") host.saveApprovedPlanToRepo(ctx, currentPlan);
+			const roles = options.roles;
+			let generatedCriteria: Awaited<ReturnType<NonNullable<typeof options.generateVerificationCriteria>>> | undefined;
+			if (roles?.verifier && options.generateVerificationCriteria) {
+				generatedCriteria = await options.generateVerificationCriteria(currentPlan);
+				if (generatedCriteria) {
+					const repoPlanSlug = host.getPlanRepoSlug();
+					if (repoPlanSlug) saveRepoPlanFile(generatedCriteria.markdown, ctx.cwd, repoPlanSlug, "criteria");
+					ctx.ui.notify(`Verification criteria ready: ${generatedCriteria.criteria.length} checks.`);
+				} else {
+					ctx.ui.notify("Verification criteria could not be generated; the verifier will judge plan steps directly.", "warning");
+				}
+			}
+			// The implementer was picked up front in the MoA picker, so approval
+			// applies it directly with no second picker. The post-approval picker
+			// is kept only as a fallback for a run restored without a roles roster.
+			let implementationSelection: { ref: ModelRef; thinking: ThinkingLevel } | undefined;
+			if (roles?.implementer) {
+				implementationSelection = { ref: roles.implementer, thinking: roles.implementerThinking ?? host.currentThinkingLevel() };
+			} else {
+				implementationSelection = await showImplementingModelPicker(ctx, host.currentThinkingLevel());
+			}
+			if (implementationSelection) {
+				await host.applyImplementingSelection(
+					ctx,
+					implementationSelection,
+					`Switched to ${modelRefLabel(implementationSelection.ref)} for implementation.`,
+				);
+			}
+			host.exitPlanMode(ctx);
+			const filePath = getPlanFilePath();
+			const handoff: ImplementationHandoff = {
+				plan: currentPlan,
+				planFilePath: filePath,
+				repoPlanSlug: host.getPlanRepoSlug(),
+				model: implementationSelection?.ref ?? ctx.model,
+				thinking: implementationSelection?.thinking ?? host.currentThinkingLevel(),
+				verifier: roles?.verifier,
+				verifierThinking: roles?.verifierThinking,
+				verificationCriteria: generatedCriteria?.markdown,
+				verificationRepairs: 0,
+				timestamp: Date.now(),
+			};
+			host.setImplementationHandoff(handoff);
+			if (handoff.model) {
+				// The review overlay pauses the table without settling synthesis. Close
+				// that row before implementation so its status and last tool activity
+				// cannot continue rendering as a second active agent.
+				widget.settleRoleRow("Synthesize", "done");
+				widget.setPhaseModels({
+					Plan: proposers,
+					Synthesize: getSynthesizer(),
+					Implement: handoff.model,
+					Verify: roles?.verifier,
+				});
+				widget.switchToImplementing(handoff.model, "implementing plan…", handoff.thinking);
+				host.adoptProgressWidget(widget);
+			}
+			host.markImplementationPending(ctx);
+			host.pi.sendUserMessage(buildImplementationKickoffMessage(currentPlan, filePath), TRIGGER_TURN);
+		} else {
+			ctx.ui.notify("Continuing to refine the MoA-synthesized plan.");
+			host.pi.sendUserMessage(`The plan file already contains a Mixture-of-Agents synthesized plan for this request. Read it, refine it further if needed, and call exit_plan_mode when ready.`, TRIGGER_TURN);
+		}
+		return "done";
+	}
+}

package/src/moa/runContext.ts

@@ -0,0 +1,118 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { ProposalFileSet } from "../planning/planFile.ts";
+import type { CancelSession } from "../runtime/cancelRun.ts";
+import type { SingleResult } from "../runtime/results.ts";
+import type { ThinkingLevel, ModelRef } from "../shared/modelRefs.ts";
+import type { ObserveSession } from "../ui/observeOverlay.ts";
+import type { MoaProgressWidget } from "../ui/moaProgressWidget.ts";
+import type { MfPlanInfo } from "./planInfo.ts";
+
+import type { ImplementationHandoff } from "./implementationRetry.ts";
+import type { VerificationCriterion } from "./verificationCriteria.ts";
+
+export interface MoaRunHost {
+	pi: ExtensionAPI;
+	getPlanRepoSlug(): string | undefined;
+	getActiveObserveSession(): ObserveSession | undefined;
+	setActiveObserveSession(session: ObserveSession | undefined): void;
+	getActiveRunMoaInfo(): MfPlanInfo | undefined;
+	setActiveRunMoaInfo(info: MfPlanInfo | undefined): void;
+	persistState(): void;
+	currentThinkingLevel(): ThinkingLevel;
+	applyImplementingSelection(
+		ctx: ExtensionContext,
+		selection: { ref: ModelRef; thinking: ThinkingLevel },
+		successNotice: string,
+	): Promise<void>;
+	exitPlanMode(ctx: ExtensionContext): void;
+	saveApprovedPlanToRepo(ctx: ExtensionContext, plan: string): void;
+	getImplementationHandoff(): ImplementationHandoff | undefined;
+	setImplementationHandoff(handoff: ImplementationHandoff | undefined): void;
+	markImplementationPending(ctx?: ExtensionContext): void;
+	/**
+	 * Latch the footer's unrecoverable-error dot and repaint. Only for flows that
+	 * stop with nothing left to try automatically — not for warnings, fallbacks,
+	 * retry dialogs, or user cancellation.
+	 */
+	noteRunError(ctx: ExtensionContext, message: string): void;
+	/**
+	 * Take ownership of the MoA progress widget from orchestration, so it stays
+	 * mounted across in-session implementation and verification. Orchestration's
+	 * own `finally` skips its stop when the controller holds the widget.
+	 */
+	adoptProgressWidget(widget: MoaProgressWidget): void;
+	getActiveProgressWidget(): MoaProgressWidget | undefined;
+	/** The orchestration widget while a run is in fan-out, synthesis, or review. */
+	getRunningProgressWidget(): MoaProgressWidget | undefined;
+	setRunningProgressWidget(widget: MoaProgressWidget | undefined): void;
+	stopActiveProgressWidget(): void;
+	/**
+	 * Publish (or clear) the F4-cancellable session the input triggers open the
+	 * cancel overlay against. The verification phase uses this to make its
+	 * read-only verifier subprocess cancellable, mirroring how fan-out/synthesis
+	 * publish their run via the plan-prompt session.
+	 */
+	setActiveCancelSession(session: CancelSession | undefined): void;
+}
+
+/**
+ * Models chosen up front in the MoA picker for the post-approval phases:
+ * the implementer that writes the approved plan in-session, and the verifier
+ * that judges the result against the plan. Threaded from the picker through
+ * orchestration into the review loop and the implementation handoff.
+ */
+export interface MoaRoles {
+	implementer: ModelRef;
+	implementerThinking?: ThinkingLevel;
+	verifier: ModelRef;
+	verifierThinking?: ThinkingLevel;
+}
+
+export interface SynthesisRoundResult {
+	result: SingleResult;
+	cancelled?: boolean;
+	failed?: boolean;
+}
+
+export interface SucceededProposal {
+	ref: ModelRef;
+	plan: string;
+	originalIndex: number;
+}
+
+export interface ReviewLoopOptions {
+	host: MoaRunHost;
+	ctx: ExtensionContext;
+	session: CancelSession;
+	widget: MoaProgressWidget;
+	proposers: ModelRef[];
+	succeeded: SucceededProposal[];
+	initialPlan: string;
+	synthConversation: string[];
+	getSynthesizer(): ModelRef;
+	/** Current synthesizer thinking level, read live so review-round activations show the active selection. */
+	getSynthesizerThinking(): ThinkingLevel | undefined;
+	getLatestVerdicts(): string | null;
+	setLatestVerdicts(markdown: string): void;
+	rebuildSynthTask(): void;
+	getSynthTask(): string;
+	runSynthWithRecovery(task: string): Promise<SynthesisRoundResult>;
+	warnIfMutated(phase: string): Promise<void>;
+	roles?: MoaRoles;
+	generateVerificationCriteria?(plan: string): Promise<{ criteria: VerificationCriterion[]; markdown: string } | undefined>;
+}
+
+export interface MoaRunContext {
+	host: MoaRunHost;
+	session: CancelSession;
+	widget: MoaProgressWidget;
+	synthesizer: ModelRef;
+	synthesizerThinking: ThinkingLevel | undefined;
+	synthConversation: string[];
+	latestVerdicts: string | null;
+	proposalFiles: ProposalFileSet | null;
+	observeSession: ObserveSession | undefined;
+	previousObserveSession: ObserveSession | undefined;
+	roles?: MoaRoles;
+}