pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/harness/loop-runtime.ts

@@ -6,7 +6,12 @@
  *   pick task -> assign model -> code -> run tests -> review diff
  *   -> if failed: repair
  *   -> if quota_limit: pause and resume later
- *   -> if blocked: escalate to human
+ *   -> if context_full: compact + auto-resume
+ *
+ * Compact integration (RFC-0028):
+ *   Uses CompactOrchestrator to proactively manage context window.
+ *   On context_full: full compact + continue prompt + auto-retry
+ *   On quota: pause job for later resume
  */
 
 import type {
@@ -15,87 +20,201 @@ import type {
 	JobStatus,
 	RuntimeCheckpoint,
 	RuntimeTask,
-} from "../packages/types/src/runtime-types.ts";
-import { JobStateMachine } from "./job-state-machine.ts";
-import { TaskGraphManager } from "./task-graph.ts";
-import { RepairEngine } from "./repair-engine.ts";
-import type { CheckpointManager } from "./job-state-machine.ts";
+	CompactableMessage,
+	InvokeWithCompactOptions,
+	InvokeResult,
+	CompactResult,
+	RuntimeEvent,
+} from "../packages/types/src/runtime-types.js";
+import {
+	JobStateMachine,
+	type CheckpointManager,
+} from "./job-state-machine.js";
+import {
+	CompactOrchestrator,
+	type CompactOrchestratorCallbacks,
+} from "./context-compact-orchestrator.js";
+import {
+	type SessionMemoryManager,
+	createSessionMemoryManager,
+} from "./session-memory.js";
+import { AutoCompactEngine } from "./auto-compact.js";
+import { OutputLimitHandler } from "./output-limit-handler.js";
+import {
+	type ForkedSummarizer,
+	createForkedSummarizer,
+} from "./forked-summarizer.js";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_COMPACT_RETRIES = 3;
+const DEFAULT_MAX_OUTPUT_TOKENS = 4096;
+
+// ─── Lifecycle Callbacks ────────────────────────────────────────────────────
+
+export interface LoopCallbacks {
+	/** Fetch next task from queue */
+	onPickTask?: () => Promise<RuntimeTask | null>;
+	/** Pick the best model for a task */
+	onPickModel?: (task: RuntimeTask) => Promise<string>;
+	/** Invoke the agent (returns full assistant text) */
+	onInvokeAgent?: (opts: InvokeWithCompactOptions) => Promise<InvokeResult>;
+	/** Run local tests */
+	onRunTests?: (task: RuntimeTask) => Promise<boolean>;
+	/** Run E2E tests */
+	onRunE2E?: (task: RuntimeTask) => Promise<boolean>;
+	/** Review the diff and decide next step */
+	onReview?: (
+		task: RuntimeTask,
+		testResults: { unit: boolean; e2e: boolean },
+	) => Promise<"approve" | "repair" | "escalate">;
+	/** Repair a failed task */
+	onRepair?: (
+		task: RuntimeTask,
+		error: string,
+	) => Promise<{ success: boolean; patch?: string }>;
+	/** Escalate to human */
+	onEscalate?: (task: RuntimeTask, reason: string) => Promise<void>;
+	/** Notify on quota events */
+	onQuotaEvent?: (
+		event: "paused" | "resumed" | "exhausted",
+		provider?: string,
+	) => Promise<void>;
+	/** Save checkpoint (call persistence layer) */
+	onCheckpoint?: (checkpoint: RuntimeCheckpoint) => Promise<void>;
+	/** Notify each loop iteration */
+	onIteration?: (iteration: number, status: JobStatus) => void;
+	/** Called after every compaction with summary */
+	onCompaction?: (result: CompactResult) => void;
+}
+
+// ─── Loop Result ───────────────────────────────────────────────────────────
 
 export interface LoopResult {
 	success: boolean;
 	completed: boolean;
 	iterations: number;
 	error?: string;
+	finalCheckpoint?: RuntimeCheckpoint;
+	/** Total compactions performed */
+	totalCompactions?: number;
 }
 
-export interface LoopCallbacks {
-	onTaskStart?: (taskId: string) => Promise<void>;
-	onTaskComplete?: (taskId: string, report: unknown) => Promise<void>;
-	onTaskFailure?: (taskId: string, error: string) => Promise<void>;
-	onQuotaExceeded?: (provider: string) => Promise<void>;
-	onHumanEscalation?: (taskId: string, reason: string) => Promise<void>;
-	onIteration?: (iteration: number, status: string) => Promise<void>;
-	invokeAgent?: (
-		task: RuntimeTask,
-		context: unknown,
-	) => Promise<{ success: boolean; output?: string; error?: string }>;
-	runTests?: (
-		taskId: string,
-		worktreePath?: string,
-	) => Promise<{ passed: boolean; output?: string }>;
-	runReview?: (
-		taskId: string,
-		diffPath: string,
-	) => Promise<{ approved: boolean; comments?: string }>;
-}
+// ─── Loop Runtime ───────────────────────────────────────────────────────────
 
 export class LoopRuntime {
-	private state: LoopState;
-	private machine: JobStateMachine;
-	private graph: TaskGraphManager;
-	private repairEngine: RepairEngine;
-	private callbacks: LoopCallbacks;
+	private readonly config: Required<LoopConfig>;
+	private readonly state: LoopState;
+	private readonly jobState: JobStateMachine;
+	private readonly callbacks: LoopCallbacks;
 	private running = false;
 	private paused = false;
 
+	// Compact-related state
+	private readonly maxCompactRetries: number;
+	private readonly maxOutputTokens: number;
+	private compactOrchestrator?: CompactOrchestrator;
+	private forkedSummarizer?: ForkedSummarizer;
+	private sessionMemory?: SessionMemoryManager;
+	private autoCompactEngine?: AutoCompactEngine;
+	private totalCompactions = 0;
+
 	constructor(
 		config: LoopConfig,
-		checkpointManager: CheckpointManager,
-		callbacks: LoopCallbacks,
+		callbacks: LoopCallbacks & {
+			/** Provider for compact orchestrator */
+			provider?: string;
+			/** Model for summarization */
+			summarizerModel?: string;
+			/** Context window size */
+			contextWindowSize?: number;
+		},
 	) {
+		this.callbacks = callbacks;
+		this.maxCompactRetries =
+			config.maxRepairAttempts ?? DEFAULT_MAX_COMPACT_RETRIES;
+		this.maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS;
+
+		this.config = {
+			jobId: config.jobId,
+			requirement: config.requirement,
+			providerPolicy: config.providerPolicy ?? {
+				plannerProvider: "openai",
+				codeProviders: ["openai"],
+				reviewProvider: "openai",
+				fallbackProviders: [],
+			},
+			maxIterations: config.maxIterations ?? 1000,
+			autoCheckpoint: config.autoCheckpoint ?? true,
+			checkpointInterval: config.checkpointInterval ?? 50,
+			pauseOnQuota: config.pauseOnQuota ?? true,
+			maxRepairAttempts: config.maxRepairAttempts ?? 3,
+		};
+
 		this.state = {
 			jobId: config.jobId,
 			iteration: 0,
-			status: "running",
+			status: "created",
+			currentTaskId: null,
+			lastCheckpoint: null,
 		};
 
-		this.machine = new JobStateMachine({ checkpointManager });
-		this.graph = new TaskGraphManager({ jobId: config.jobId });
-		this.repairEngine = new RepairEngine(config.jobId);
-		this.callbacks = callbacks;
-	}
+		this.jobState = new JobStateMachine({
+			checkpointManager: {
+				async save(ckpt: Parameters<CheckpointManager["save"]>[0]) {
+					await callbacks.onCheckpoint?.(ckpt);
+				},
+				async load(_jobId: string) {
+					return null;
+				},
+				async appendEvent(_jobId: string, _event: RuntimeEvent) {
+					// no-op for now
+				},
+			},
+		});
+
+		// Initialize session memory
+		this.sessionMemory = createSessionMemoryManager(config.jobId);
+
+		// Initialize auto-compact engine
+		this.autoCompactEngine = new AutoCompactEngine({
+			jobId: config.jobId,
+			requirement: config.requirement,
+		});
+
+		// Initialize compact orchestrator if agent callback provided
+		if (callbacks.onInvokeAgent) {
+			this.compactOrchestrator = new CompactOrchestrator({
+				jobId: config.jobId,
+				provider: callbacks.provider ?? "openai",
+				model: callbacks.summarizerModel ?? "gpt-4",
+				contextWindowSize: callbacks.contextWindowSize,
+			});
 
-	/**
-	 * Initialize the loop with a job
-	 */
-	async init(requirement: string): Promise<void> {
-		await this.machine.createJob(this.state.jobId, requirement);
-		await this.machine.transition("planning");
+			// Initialize forked summarizer if model provided
+			if (callbacks.summarizerModel && callbacks.onInvokeAgent) {
+				// Wrap onInvokeAgent to match ForkedSummarizer's InvokeOptions
+				const wrappedInvoke = async (opts: {
+					messages: Array<{ role: string; content: string }>;
+					model: string;
+					maxOutputTokens: number;
+					systemPrompt?: string;
+				}) => {
+					return callbacks.onInvokeAgent!(opts as InvokeWithCompactOptions);
+				};
+				this.forkedSummarizer = createForkedSummarizer(
+					callbacks.summarizerModel,
+					wrappedInvoke,
+				);
+			}
+		}
 	}
 
-	/**
-	 * Resume from checkpoint
-	 */
-	async resume(checkpoint: RuntimeCheckpoint): Promise<void> {
-		this.state.iteration = 0;
-		await this.machine.resumeJob(checkpoint.jobId);
-	}
+	// ─── Public API ─────────────────────────────────────────────────────────
 
-	/**
-	 * Run the main loop
-	 */
 	async run(): Promise<LoopResult> {
 		this.running = true;
+		this.state.status = "running";
 
 		try {
 			while (this.running) {
@@ -108,230 +227,473 @@ export class LoopRuntime {
 				this.state.iteration++;
 
 				// Check iteration limit
-				if (this.state.iteration > 1000) {
+				if (this.state.iteration > this.config.maxIterations) {
 					return {
 						success: false,
 						completed: false,
 						iterations: this.state.iteration,
 						error: "Max iterations exceeded",
+						totalCompactions: this.totalCompactions,
 					};
 				}
 
-				await this.callbacks.onIteration?.(
-					this.state.iteration,
-					this.state.status,
-				);
+				this.callbacks.onIteration?.(this.state.iteration, this.state.status);
 
 				// Check job status
-				if (this.machine.isTerminal()) {
-					return {
-						success: true,
-						completed: true,
-						iterations: this.state.iteration,
-					};
+				const statusSummary = await this.jobState.getStatusSummary();
+				if (statusSummary?.status === "paused_quota") {
+					await this.handleQuotaPause();
+					continue;
 				}
 
-				// Pick next task
-				const nextTask = await this.pickNextTask();
-				if (!nextTask) {
-					// No more tasks, job is complete
-					await this.machine.transition("ready_for_client");
-					return {
-						success: true,
-						completed: true,
-						iterations: this.state.iteration,
-					};
+				// Pick a task
+				const task = await this.callbacks.onPickTask?.();
+				if (!task) {
+					this.state.status = "archived";
+					break;
 				}
 
-				this.state.currentTaskId = nextTask.id;
-				this.state.status = "running";
+				this.state.currentTaskId = task.id;
+				await this.executeTaskWithCompact(task);
 
-				// Execute task
-				const result = await this.executeTask(nextTask);
-
-				if (!result.success) {
-					// Handle failure
-					const { repairTask } = this.repairEngine.analyzeAndRepair(
-						nextTask.id,
-						result.error ?? "Unknown error",
-					);
-
-					if (this.repairEngine.shouldEscalate(repairTask.id)) {
-						await this.machine.transition("waiting_human");
-						await this.callbacks.onHumanEscalation?.(
-							nextTask.id,
-							result.error ?? "Unknown error",
-						);
-					} else {
-						await this.machine.transition("repairing");
-						// Continue loop to attempt repair
-					}
-				} else {
-					// Task succeeded
-					this.graph.updateTaskStatus(nextTask.id, "done");
-					await this.machine.transition("testing");
-
-					// Run tests
-					const testResult = await this.callbacks.runTests?.(
-						nextTask.id,
-						nextTask.worktreePath,
-					);
-					if (!testResult?.passed) {
-						await this.machine.transition("repairing");
-						this.graph.updateTaskStatus(nextTask.id, "failed");
-					} else {
-						await this.machine.transition("reviewing");
-
-						// Run review
-						const reviewResult = await this.callbacks.runReview?.(
-							nextTask.id,
-							nextTask.worktreePath ?? "",
-						);
-						if (!reviewResult?.approved) {
-							await this.machine.transition("repairing");
-						}
-					}
+				// Auto-checkpoint
+				if (
+					this.config.autoCheckpoint &&
+					this.state.iteration % this.config.checkpointInterval === 0
+				) {
+					await this.saveCheckpoint();
 				}
-
-				await this.saveCheckpoint();
 			}
 
 			return {
-				success: true,
-				completed: false,
+				success: this.state.status !== "archived",
+				completed: this.state.status === "archived",
 				iterations: this.state.iteration,
-			};
-		} catch (error) {
-			return {
-				success: false,
-				completed: false,
-				iterations: this.state.iteration,
-				error: String(error),
+				finalCheckpoint: this.state.lastCheckpoint ?? undefined,
+				totalCompactions: this.totalCompactions,
 			};
 		} finally {
 			this.running = false;
 		}
 	}
 
-	/**
-	 * Pick the next task to execute
-	 */
-	private async pickNextTask(): Promise<RuntimeTask | null> {
-		const readyTasks = this.graph.getReadyTasks();
-
-		// Pick the first ready task that's not assigned
-		for (const task of readyTasks) {
-			if (!task.assignedAgent) {
-				this.graph.assignAgent(task.id, "loop-runtime");
-				return task as unknown as RuntimeTask;
-			}
-		}
+	pause(): void {
+		this.paused = true;
+	}
 
-		return null;
+	resume(): void {
+		this.paused = false;
+		this.state.status = "running";
 	}
 
-	/**
-	 * Execute a single task
-	 */
-	private async executeTask(task: RuntimeTask): Promise<{
-		success: boolean;
-		output?: string;
-		error?: string;
-	}> {
-		try {
-			await this.callbacks.onTaskStart?.(task.id);
+	stop(): void {
+		this.running = false;
+	}
+
+	getState(): Readonly<LoopState> {
+		return { ...this.state };
+	}
+
+	/** Get compact orchestrator for external access */
+	getCompactOrchestrator(): CompactOrchestrator | undefined {
+		return this.compactOrchestrator;
+	}
 
-			const result = await this.callbacks.invokeAgent?.(task, {
-				jobId: this.state.jobId,
-				requirement: this.machine.getCheckpoint()?.requirement,
+	/** Get session memory manager */
+	getSessionMemory(): SessionMemoryManager | undefined {
+		return this.sessionMemory;
+	}
+
+	// ─── Task Execution with Compact ───────────────────────────────────────
+
+	private async executeTaskWithCompact(task: RuntimeTask): Promise<void> {
+		// 1. Pick model
+		const model = (await this.callbacks.onPickModel?.(task)) ?? "claude";
+
+		// 2. Build compactable messages
+		const compactMessages: CompactableMessage[] = [
+			{
+				role: "system",
+				content: this.buildSystemPrompt(task),
+				timestamp: Date.now(),
+			},
+			{
+				role: "user",
+				content: `Task: ${task.id}\nObjective: ${task.description ?? "See task graph."}`,
+				timestamp: Date.now(),
+			},
+		];
+
+		// 3. Inject session memory if available
+		const sessionMemoryContext = this.sessionMemory?.getMemoryForContext();
+		if (sessionMemoryContext) {
+			compactMessages.push({
+				role: "system",
+				content: sessionMemoryContext,
+				timestamp: Date.now(),
+				metadata: { sessionMemory: true },
 			});
+		}
+
+		const outputLimitHandler = new OutputLimitHandler({
+			jobId: this.config.jobId,
+			taskId: task.id,
+		});
+
+		// 4. Execute with compact support
+		let compactRetries = 0;
+
+		while (compactRetries < this.maxCompactRetries) {
+			// Build invoke options
+			const invokeOptions: InvokeWithCompactOptions = {
+				messages: compactMessages,
+				model,
+				maxOutputTokens: this.maxOutputTokens,
+				tools: task.tools,
+				systemPrompt: task.instructions,
+			};
+
+			// Use compact orchestrator if available
+			if (this.compactOrchestrator && this.callbacks.onInvokeAgent) {
+				const orchestratorCallbacks = this.buildCompactCallbacks(task, model);
+				const result = await this.compactOrchestrator.invokeWithCompact(
+					invokeOptions,
+					orchestratorCallbacks,
+				);
+
+				if (result.success) {
+					const continued = await this.handleAutoContinuation(
+						compactMessages,
+						result,
+						task,
+						outputLimitHandler,
+					);
+					if (continued) {
+						continue;
+					}
 
-			if (result?.success) {
-				await this.callbacks.onTaskComplete?.(task.id, {
-					output: result.output,
-				});
-				return { success: true, output: result.output };
-			} else {
-				const error = result?.error ?? "Agent returned failure";
-				await this.callbacks.onTaskFailure?.(task.id, error);
-				return { success: false, error };
+					this.handleInvokeSuccess(compactMessages, result, task);
+					outputLimitHandler.reset();
+					await this.runTestsAndReview(task, compactMessages);
+					return;
+				}
+
+				// Check for circuit breaker
+				if (this.compactOrchestrator.isCircuitBroken()) {
+					this.state.status = "blocked";
+					throw new Error(
+						`Compact circuit breaker engaged after ${this.compactOrchestrator.getConsecutiveFailures()} failures.`,
+					);
+				}
+
+				// Compact happened — retry
+				if (result.compactResult) {
+					compactRetries++;
+					this.totalCompactions++;
+					this.onCompactionOccurred(result.compactResult);
+
+					// Append continue message
+					if (result.continueMessage) {
+						compactMessages.push({
+							role: "user",
+							content: result.continueMessage,
+							timestamp: Date.now(),
+						});
+					}
+					continue;
+				}
+
+				// Error without compact — surface it
+				throw new Error(result.error ?? "Unknown invoke error");
 			}
-		} catch (error) {
-			return { success: false, error: String(error) };
+
+			// Fallback: direct invoke without orchestrator
+			const result = await this.callbacks.onInvokeAgent?.(invokeOptions);
+			if (!result || !result.success) {
+				throw new Error(result?.error ?? "Invoke failed");
+			}
+
+			const continued = await this.handleAutoContinuation(
+				compactMessages,
+				result,
+				task,
+				outputLimitHandler,
+			);
+			if (continued) {
+				continue;
+			}
+
+			this.handleInvokeSuccess(compactMessages, result, task);
+			outputLimitHandler.reset();
+			await this.runTestsAndReview(task, compactMessages);
+			return;
 		}
+
+		// Max compact retries exceeded
+		this.state.status = "blocked";
+		throw new Error(`Max compact retries (${this.maxCompactRetries}) exceeded`);
+	}
+
+	private async handleAutoContinuation(
+		messages: CompactableMessage[],
+		result: InvokeResult,
+		task: RuntimeTask,
+		outputLimitHandler: OutputLimitHandler,
+	): Promise<boolean> {
+		const output = result.output ?? "";
+		const hitOutputLimit = outputLimitHandler.detectOutputLimit(result.error, {
+			finishReason: result.finishReason,
+		});
+		const hitCompactionBoundary =
+			this.autoCompactEngine?.detectCompaction(output) ?? false;
+
+		if (!hitOutputLimit && !hitCompactionBoundary) {
+			return false;
+		}
+
+		if (!outputLimitHandler.shouldContinue()) {
+			throw new Error(
+				`Output limit recovery exhausted after ${outputLimitHandler.getAttempts()} attempts for task ${task.id}.`,
+			);
+		}
+
+		this.handleInvokeSuccess(messages, result, task);
+		await outputLimitHandler.handleOutputLimit(
+			output,
+			result.finishReason ?? "length",
+		);
+
+		const continueMessage = hitCompactionBoundary
+			? (this.autoCompactEngine?.buildContinueMessage() ?? "continue")
+			: "Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if needed and continue the same task.";
+		messages.push({
+			role: "user",
+			content: continueMessage,
+			timestamp: Date.now(),
+			metadata: {
+				autoContinuation: true,
+				reason: hitCompactionBoundary ? "compaction" : "output_limit",
+				attempt: outputLimitHandler.getAttempts(),
+			},
+		});
+		return true;
 	}
 
 	/**
-	 * Pause the loop
+	 * Build compact callbacks for the orchestrator
 	 */
-	pause(): void {
-		this.paused = true;
-		this.state.status = "paused";
+	private buildCompactCallbacks(
+		task: RuntimeTask,
+		_model: string,
+	): CompactOrchestratorCallbacks {
+		return {
+			invokeAgent: async (opts) => {
+				return (
+					(await this.callbacks.onInvokeAgent?.(opts)) ?? {
+						success: false,
+						error: "No agent",
+					}
+				);
+			},
+
+			onCheckpoint: async (result) => {
+				this.callbacks.onCompaction?.(result);
+				await this.saveCheckpoint();
+			},
+
+			onPreCompact: async (_reason) => {
+				// Save partial artifacts before compact
+				// Note: we don't have beforeTokens here, but we save the state
+				this.autoCompactEngine?.saveCompactionArtifact({
+					timestamp: new Date().toISOString(),
+					jobId: this.config.jobId,
+					taskId: task.id,
+					compactedFromTokens: 0,
+					reason: _reason,
+				} as any);
+			},
+
+			onPostCompact: async (result) => {
+				// Extract facts from compacted messages for session memory
+				this.sessionMemory?.extractFacts([]);
+				this.callbacks.onCompaction?.(result);
+			},
+
+			onQuotaEvent: this.callbacks.onQuotaEvent,
+
+			summarizeViaForkedAgent: async (messages, reason) => {
+				if (this.forkedSummarizer) {
+					return this.forkedSummarizer.summarize(messages, {
+						focusOn: "work_done",
+					});
+				}
+				// Fallback to heuristic
+				return {
+					summary: `[Compact: ${reason}] Conversation summarised.`,
+					droppedCount: messages.length,
+				};
+			},
+		};
 	}
 
 	/**
-	 * Resume the loop
+	 * Handle successful invoke result
 	 */
-	async resumeLoop(): Promise<void> {
-		this.paused = false;
-		this.state.status = "running";
+	private handleInvokeSuccess(
+		messages: CompactableMessage[],
+		result: InvokeResult,
+		_task: RuntimeTask,
+	): void {
+		// Append assistant response to messages
+		messages.push({
+			role: "assistant",
+			content: result.output ?? "",
+			timestamp: Date.now(),
+			metadata: {
+				model: result.model,
+				usage: result.usage,
+			},
+		});
+
+		// Extract facts from output for session memory
+		if (result.output) {
+			this.sessionMemory?.extractFacts([
+				{
+					role: "assistant",
+					content: result.output,
+					timestamp: Date.now(),
+				},
+			]);
+		}
 	}
 
 	/**
-	 * Stop the loop
+	 * Called when compaction occurs
 	 */
-	stop(): void {
-		this.running = false;
-		this.state.status = "failed";
+	private onCompactionOccurred(result: CompactResult): void {
+		// Update session memory with compacted content
+		this.sessionMemory?.extractFacts([]);
+
+		// Save compaction event
+		this.autoCompactEngine?.saveCompactionArtifact({
+			timestamp: new Date().toISOString(),
+			jobId: this.config.jobId,
+			taskId: this.state.currentTaskId ?? "unknown",
+			compactedFromTokens: result.beforeTokens,
+			reason: result.trigger,
+			continuePrompt: result.summary,
+		} as any);
+
+		// Notify callbacks
+		this.callbacks.onCompaction?.(result);
 	}
 
 	/**
-	 * Save checkpoint
+	 * Run tests and review
 	 */
-	private async saveCheckpoint(): Promise<void> {
-		const checkpoint = this.machine.getCheckpoint();
-		if (checkpoint) {
-			await this.machine.transition(checkpoint.status, {
-				currentTaskId: this.state.currentTaskId,
+	private async runTestsAndReview(
+		task: RuntimeTask,
+		messages: CompactableMessage[],
+	): Promise<void> {
+		// Run tests
+		const unitPassed = (await this.callbacks.onRunTests?.(task)) ?? true;
+		const e2ePassed = (await this.callbacks.onRunE2E?.(task)) ?? true;
+
+		// Update session memory with test results
+		this.sessionMemory?.addTestResult(task.id, unitPassed && e2ePassed);
+
+		// Review
+		const verdict = await this.callbacks.onReview?.(task, {
+			unit: unitPassed,
+			e2e: e2ePassed,
+		});
+
+		if (verdict === "escalate") {
+			this.state.status = "waiting_human";
+			await this.callbacks.onEscalate?.(task, "Human review required");
+			this.paused = true;
+		} else if (verdict === "repair") {
+			// Append repair instruction
+			messages.push({
+				role: "user",
+				content:
+					"Tests failed. Please fix the issues and ensure all tests pass.",
+				timestamp: Date.now(),
 			});
 		}
 	}
 
 	/**
-	 * Get current state
+	 * Build system prompt for task
 	 */
-	getState(): LoopState {
-		return this.state;
+	private buildSystemPrompt(task: RuntimeTask): string {
+		const parts = [
+			task.instructions ?? "Complete the assigned task.",
+			"",
+			"## Context Management",
+			"- Keep responses concise and focused",
+			"- If context becomes full, the system will compact automatically",
+			"- Do not repeat work already done",
+		];
+
+		if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+			parts.push("", "## Acceptance Criteria");
+			for (const criteria of task.acceptanceCriteria) {
+				parts.push(`- ${criteria}`);
+			}
+		}
+
+		return parts.join("\n");
 	}
 
-	/**
-	 * Get job status
-	 */
-	getStatus(): {
-		status: JobStatus;
-		canResume: boolean;
-		isTerminal: boolean;
-	} | null {
-		const summary = this.machine.getStatusSummary();
-		if (!summary) return null;
-		return {
-			status: summary.status,
-			canResume: summary.canResume,
-			isTerminal: summary.isTerminal,
-		};
+	// ─── Quota Handling ────────────────────────────────────────────────────
+
+	private async handleQuotaPause(): Promise<void> {
+		this.paused = true;
+		this.state.status = "paused_quota";
+		this.jobState.transition("paused_quota");
+		await this.callbacks.onQuotaEvent?.("paused");
+		await this.saveCheckpoint();
 	}
 
-	/**
-	 * Check if loop is running
-	 */
-	isRunning(): boolean {
-		return this.running && !this.paused;
+	// ─── Persistence ────────────────────────────────────────────────────────
+
+	private async saveCheckpoint(): Promise<void> {
+		const now = new Date().toISOString();
+		const checkpoint: RuntimeCheckpoint = {
+			version: 1,
+			jobId: this.state.jobId,
+			requirement: this.config.requirement,
+			taskId: this.state.currentTaskId ?? undefined,
+			iteration: this.state.iteration,
+			status: this.state.status,
+			createdAt: now,
+			updatedAt: now,
+		};
+		this.state.lastCheckpoint = checkpoint;
+		await this.jobState.transition(this.state.status);
+		await this.callbacks.onCheckpoint?.(checkpoint);
 	}
 
-	/**
-	 * Check if loop is paused
-	 */
-	isPaused(): boolean {
-		return this.paused;
+	// ─── Resume from Checkpoint ────────────────────────────────────────────
+
+	async resumeFromCheckpoint(
+		checkpoint: RuntimeCheckpoint,
+	): Promise<LoopResult> {
+		this.state.iteration = checkpoint.iteration ?? 0;
+		this.state.currentTaskId = checkpoint.taskId ?? null;
+		this.state.status = checkpoint.status ?? "running";
+		this.paused = false;
+
+		// Check for pending continue prompt
+		if (this.autoCompactEngine?.hasContinuePrompt()) {
+			const continuePrompt = this.autoCompactEngine.loadContinuePrompt();
+			if (continuePrompt) {
+				// Resume will inject the continue prompt
+				this.callbacks.onIteration?.(this.state.iteration, this.state.status);
+			}
+		}
+
+		return this.run();
 	}
 }