@kodrunhq/opencode-autopilot 1.18.0 → 1.19.0

package/README.md

@@ -14,7 +14,7 @@
 
 <p align="center">
   <strong>Autonomous AI coding pipeline for OpenCode.</strong><br/>
-  Idea to shipped code &bull; 21-agent code review &bull; Adversarial model diversity &bull; Guided setup
+  Idea to shipped code &bull; 13-agent code review &bull; Adversarial model diversity &bull; Background task management &bull; Session recovery
 </p>
 
 ---
@@ -93,7 +93,7 @@ Agents are organized into 8 groups by the type of thinking they do. Each group g
 | **Architects** | oc-architect, oc-planner, autopilot | System design, planning, orchestration | Most powerful available |
 | **Challengers** | oc-critic, oc-challenger | Challenge architecture, find design flaws | Strong model, **different family from Architects** |
 | **Builders** | oc-implementer | Write production code | Strong coding model |
-| **Reviewers** | oc-reviewer + 19 review agents | Find bugs, security issues, logic errors | Strong model, **different family from Builders** |
+| **Reviewers** | oc-reviewer + 11 review agents | Find bugs, security issues, logic errors | Strong model, **different family from Builders** |
 | **Red Team** | red-team, product-thinker | Final adversarial pass, hunt exploits | **Different family from both Builders and Reviewers** |
 | **Researchers** | oc-researcher, researcher | Domain research, feasibility analysis | Good comprehension, any family |
 | **Communicators** | oc-shipper, documenter, oc-retrospector | Docs, changelogs, lesson extraction | Mid-tier model |
@@ -113,7 +113,7 @@ The installer warns when adversarial pairs share a model family:
 
 ```json
 {
-  "version": 4,
+  "version": 7,
   "configured": true,
   "groups": {
     "architects":    { "primary": "anthropic/claude-opus-4-6",   "fallbacks": ["openai/gpt-5.4"] },
@@ -125,7 +125,22 @@ The installer warns when adversarial pairs share a model family:
     "communicators": { "primary": "anthropic/claude-sonnet-4-6", "fallbacks": ["anthropic/claude-haiku-4-5"] },
     "utilities":     { "primary": "anthropic/claude-haiku-4-5",  "fallbacks": ["google/gemini-3-flash"] }
   },
-  "overrides": {}
+  "overrides": {},
+  "background": {
+    "maxSlots": 5,
+    "defaultTimeout": 300000
+  },
+  "routing": {
+    "defaultCategory": "unspecified"
+  },
+  "recovery": {
+    "maxRetries": 3,
+    "strategies": ["retry", "fallback", "checkpoint"]
+  },
+  "mcp": {
+    "enabled": true,
+    "timeout": 30000
+  }
 }
 ```
 
@@ -190,12 +205,12 @@ The `oc_review` tool provides a 4-stage multi-agent review pipeline:
 
 **Stage 4 -- Report or fix cycle:** CRITICAL findings with actionable fixes trigger an automatic fix cycle; everything else lands in the final report.
 
-### 21 Review Agents
+### 13 Review Agents
 
 | Category | Agents | When selected |
 |----------|--------|--------------|
-| **Universal** (always run) | logic-auditor, security-auditor, code-quality-auditor, test-interrogator, silent-failure-hunter, contract-verifier | Every review |
-| **Stack-aware** (auto-selected) | type-soundness, react-patterns-auditor, go-idioms-auditor, python-django-auditor, rust-safety-auditor, database-auditor, auth-flow-verifier, state-mgmt-auditor, concurrency-checker, scope-intent-verifier, wiring-inspector, dead-code-scanner, spec-checker | Based on changed file types |
+| **Universal** (always run) | logic-auditor, security-auditor, code-quality-auditor, test-interrogator, code-hygiene-auditor, contract-verifier | Every review |
+| **Stack-aware** (auto-selected) | architecture-verifier, database-auditor, correctness-auditor, frontend-auditor, language-idioms-auditor | Based on changed file types |
 | **Sequenced** (run last) | red-team, product-thinker | After all findings collected |
 
 Review memory persists per project -- false positives are tracked and suppressed in future reviews (auto-pruned after 30 days).
@@ -242,12 +257,19 @@ Config lives at `~/.config/opencode/opencode-autopilot.json`. Run `bunx @kodrunh
 | `confidence.thresholds.proceed` | `HIGH`, `MEDIUM`, `LOW` | `MEDIUM` |
 | `confidence.thresholds.abort` | `HIGH`, `MEDIUM`, `LOW` | `LOW` |
 | `fallback.enabled` | `true` / `false` | `true` |
+| `background.maxSlots` | `1`-`10` | `5` |
+| `background.defaultTimeout` | milliseconds | `300000` |
+| `routing.defaultCategory` | category string | `"unspecified"` |
+| `recovery.maxRetries` | `1`-`10` | `3` |
+| `recovery.strategies` | array of strategy names | `["retry", "fallback", "checkpoint"]` |
+| `mcp.enabled` | `true` / `false` | `true` |
+| `mcp.timeout` | milliseconds | `30000` |
 
-Config auto-migrates across schema versions (v1 -> v2 -> v3 -> v4).
+Config auto-migrates across schema versions (v1 -> v2 -> v3 -> v4 -> v5 -> v6 -> v7).
 
 ## Tools
 
-The plugin registers 11 tools, all prefixed with `oc_` to avoid conflicts with OpenCode built-ins:
+The plugin registers 25 tools, all prefixed with `oc_` to avoid conflicts with OpenCode built-ins:
 
 | Tool | Purpose |
 |------|---------|
@@ -262,13 +284,29 @@ The plugin registers 11 tools, all prefixed with `oc_` to avoid conflicts with O
 | `oc_create_agent` | Create custom agents in-session |
 | `oc_create_skill` | Create custom skills in-session |
 | `oc_create_command` | Create custom commands in-session |
+| `oc_background` | Manage background tasks (spawn, monitor, cancel) |
+| `oc_loop` | Start/stop autonomy loop with verification checkpoints |
+| `oc_delegate` | Category-based task routing with skill injection |
+| `oc_recover` | Session recovery with strategy selection |
+| `oc_doctor` | Run plugin health diagnostics |
+| `oc_quick` | Quick-mode pipeline bypass for trivial tasks |
+| `oc_hashline_edit` | Hash-anchored line edits with FNV-1a verification |
+| `oc_logs` | Query structured session logs |
+| `oc_session_stats` | Session statistics and token usage |
+| `oc_pipeline_report` | Generate pipeline execution report |
+| `oc_summary` | Session summary generation |
+| `oc_mock_fallback` | Fallback chain testing with mock providers |
+| `oc_stocktake` | Audit installed assets (agents, skills, commands) |
+| `oc_update_docs` | Detect docs affected by code changes |
+| `oc_memory_status` | Memory system status and statistics |
+| `oc_memory_preferences` | Manage user preference observations |
 
 ## Architecture
 
 ```
 src/
 +-- index.ts                 Plugin entry -- registers tools, hooks, fallback handlers
-+-- config.ts                Zod-validated config with v1->v2->v3->v4 migration
++-- config.ts                Zod-validated config with v1->v7 migration chain
 +-- installer.ts             Self-healing asset copier (COPYFILE_EXCL, never overwrites)
 +-- registry/
 |   +-- types.ts             GroupId, AgentEntry, GroupDefinition, DiversityRule, ...
@@ -278,13 +316,57 @@ src/
 |   +-- doctor.ts            Shared diagnosis logic (CLI + tool)
 +-- tools/                   Tool definitions (thin wrappers calling *Core functions)
 +-- templates/               Pure functions: input -> markdown string
-+-- review/                  21-agent review engine, stack gate, memory, severity
++-- review/                  13-agent review engine, stack gate, memory, severity
 +-- orchestrator/
 |   +-- handlers/            Per-phase state machine handlers
 |   +-- fallback/            Model fallback: classifier, manager, state, chain resolver
 |   +-- artifacts.ts         Phase artifact path management
 |   +-- lesson-memory.ts     Cross-run lesson persistence
 |   +-- schemas.ts           Pipeline state Zod schemas
++-- background/              Background task management with slot-based concurrency
+|   +-- database.ts          SQLite persistence for task state
+|   +-- state-machine.ts     Task lifecycle (queued -> running -> completed/failed)
+|   +-- slot-manager.ts      Concurrent slot allocation and limits
+|   +-- executor.ts          Task execution with timeout handling
+|   +-- manager.ts           High-level API combining all background components
++-- autonomy/                Autonomy loop with verification checkpoints
+|   +-- state.ts             Loop state tracking (iterations, context accumulation)
+|   +-- completion.ts        Completion detection via positive/negative signals
+|   +-- verification.ts      Post-iteration verification (tests, lint, artifacts)
+|   +-- controller.ts        Loop lifecycle management (start, iterate, stop)
++-- routing/                 Category-based task routing
+|   +-- categories.ts        Category definitions with model and skill mappings
+|   +-- classifier.ts        Intent classification from task descriptions
+|   +-- engine.ts            Routing engine combining classification + delegation
++-- recovery/                Session recovery and failure resilience
+|   +-- classifier.ts        Failure classification (transient, permanent, partial)
+|   +-- strategies.ts        Recovery strategies (retry, fallback, checkpoint)
+|   +-- orchestrator.ts      Strategy selection and execution
+|   +-- persistence.ts       Checkpoint save/restore via SQLite
++-- context/                 Context window management and injection
+|   +-- discovery.ts         Active context discovery from session state
+|   +-- budget.ts            Token budget allocation across injection sources
+|   +-- injector.ts          System prompt injection orchestrator
+|   +-- compaction-handler.ts  Context compaction when approaching limits
++-- ux/                      User experience surfaces
+|   +-- notifications.ts     Toast and inline notification system
+|   +-- progress.ts          Progress tracking for multi-step operations
+|   +-- task-status.ts       Task status formatting and display
+|   +-- context-warnings.ts  Context usage warnings and suggestions
+|   +-- error-hints.ts       Actionable error hints with fix suggestions
+|   +-- session-summary.ts   End-of-session summary generation
++-- mcp/                     MCP (Model Context Protocol) skill integration
+|   +-- types.ts             MCP server and tool type definitions
+|   +-- manager.ts           MCP server lifecycle management
+|   +-- scope-filter.ts      Scope-based MCP server filtering
++-- kernel/                  Database primitives and concurrency
+|   +-- transaction.ts       SQLite transactions with retry on SQLITE_BUSY
+|   +-- retry.ts             Exponential backoff retry for busy errors
++-- logging/                 Structured logging with sinks and rotation
++-- memory/                  Smart dual-scope memory (project patterns + user preferences)
++-- observability/           Session observability and structured event logging
++-- skills/                  Adaptive skill loading and injection
++-- health/                  Plugin self-diagnostics
 +-- utils/                   Validators, paths, fs-helpers, gitignore management
 
 bin/
@@ -292,7 +374,7 @@ bin/
 ```
 
 **Dependency flow** (strictly top-down, no cycles):
-`index.ts` -> `tools/*` -> `registry/*` + `templates/*` + `utils/*` -> Node built-ins + `yaml`
+`index.ts` -> `tools/*` -> `registry/*` + `templates/*` + `utils/*` + `kernel/*` -> Node built-ins + `yaml`
 
 **Key patterns:**
 - **Declarative registry** -- adding an agent = one line in AGENT_REGISTRY, everything derives from it
@@ -310,7 +392,7 @@ bun install
 bun test && bun run lint
 ```
 
-834 tests across 64 files. No build step -- Bun runs TypeScript natively.
+1790+ tests across 190 files. No build step -- Bun runs TypeScript natively.
 
 ## License
 

package/assets/commands/oc-update-docs.md

@@ -1,7 +1,7 @@
 ---
 # opencode-autopilot
 description: Detect documentation affected by recent code changes and suggest updates
-agent: documenter
+agent: coder
 ---
 
 Invoke the `oc_update_docs` tool to analyze recent code changes and identify documentation that may need updating.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kodrunhq/opencode-autopilot",
-	"version": "1.18.0",
+	"version": "1.19.0",
 	"description": "Curated agents, skills, and commands for the OpenCode AI coding CLI — autonomous orchestrator, multi-agent code review, model fallback, and in-session asset creation tools.",
 	"main": "src/index.ts",
 	"keywords": [

package/src/agents/index.ts

@@ -4,11 +4,7 @@ import { resolveModelForAgent } from "../registry/resolver";
 import type { AgentOverride, GroupModelAssignment } from "../registry/types";
 import { autopilotAgent } from "./autopilot";
 import { coderAgent } from "./coder";
-import { dbSpecialistAgent } from "./db-specialist";
 import { debuggerAgent } from "./debugger";
-import { devopsAgent } from "./devops";
-import { documenterAgent } from "./documenter";
-import { frontendEngineerAgent } from "./frontend-engineer";
 import { metaprompterAgent } from "./metaprompter";
 import { pipelineAgents } from "./pipeline/index";
 import { plannerAgent } from "./planner";
@@ -25,11 +21,7 @@ interface AgentConfig {
 export const agents = {
 	autopilot: autopilotAgent,
 	coder: coderAgent,
-	"db-specialist": dbSpecialistAgent,
 	debugger: debuggerAgent,
-	devops: devopsAgent,
-	documenter: documenterAgent,
-	"frontend-engineer": frontendEngineerAgent,
 	metaprompter: metaprompterAgent,
 	planner: plannerAgent,
 	"pr-reviewer": prReviewerAgent,
@@ -157,11 +149,7 @@ export async function configHook(config: Config, configPath?: string): Promise<v
 
 export { autopilotAgent } from "./autopilot";
 export { coderAgent } from "./coder";
-export { dbSpecialistAgent } from "./db-specialist";
 export { debuggerAgent } from "./debugger";
-export { devopsAgent } from "./devops";
-export { documenterAgent } from "./documenter";
-export { frontendEngineerAgent } from "./frontend-engineer";
 export { metaprompterAgent } from "./metaprompter";
 export { plannerAgent } from "./planner";
 export { prReviewerAgent } from "./pr-reviewer";

package/src/agents/pipeline/index.ts

@@ -3,11 +3,9 @@ import { AGENT_NAMES } from "../../orchestrator/handlers/types";
 import { ocArchitectAgent } from "./oc-architect";
 import { ocChallengerAgent } from "./oc-challenger";
 import { ocCriticAgent } from "./oc-critic";
-import { ocExplorerAgent } from "./oc-explorer";
 import { ocImplementerAgent } from "./oc-implementer";
 import { ocPlannerAgent } from "./oc-planner";
 import { ocResearcherAgent } from "./oc-researcher";
-import { ocRetrospectorAgent } from "./oc-retrospector";
 import { ocReviewerAgent } from "./oc-reviewer";
 import { ocShipperAgent } from "./oc-shipper";
 
@@ -16,10 +14,8 @@ export const pipelineAgents: Readonly<Record<string, Readonly<AgentConfig>>> = O
 	[AGENT_NAMES.CHALLENGE]: ocChallengerAgent,
 	[AGENT_NAMES.ARCHITECT]: ocArchitectAgent,
 	[AGENT_NAMES.CRITIC]: ocCriticAgent,
-	[AGENT_NAMES.EXPLORE]: ocExplorerAgent,
 	[AGENT_NAMES.PLAN]: ocPlannerAgent,
 	[AGENT_NAMES.BUILD]: ocImplementerAgent,
 	[AGENT_NAMES.REVIEW]: ocReviewerAgent,
 	[AGENT_NAMES.SHIP]: ocShipperAgent,
-	[AGENT_NAMES.RETROSPECTIVE]: ocRetrospectorAgent,
 } as const);

package/src/autonomy/completion.ts

@@ -0,0 +1,52 @@
+const EXPLICIT_SIGNALS = Object.freeze(["all tasks completed", "complete", "finished", "done"]);
+const TODO_SIGNALS = Object.freeze(["all todos completed", "no remaining tasks"]);
+const NEGATIVE_SIGNALS = Object.freeze(["still working", "in progress", "next step"]);
+
+export interface CompletionDetectionResult {
+	readonly isComplete: boolean;
+	readonly confidence: number;
+	readonly signals: readonly string[];
+}
+
+function countMatches(content: string, phrases: readonly string[]): readonly string[] {
+	return phrases.filter((phrase) => new RegExp(`\\b${phrase}\\b`, "i").test(content));
+}
+
+function clampConfidence(value: number): number {
+	return Math.max(0, Math.min(1, value));
+}
+
+export function detectCompletion(transcript: readonly string[]): CompletionDetectionResult {
+	const normalizedTranscript = transcript.join("\n").toLowerCase();
+	const explicitMatches = countMatches(normalizedTranscript, EXPLICIT_SIGNALS);
+	const todoMatches = countMatches(normalizedTranscript, TODO_SIGNALS);
+	const negativeMatches = countMatches(normalizedTranscript, NEGATIVE_SIGNALS);
+	const signals = Object.freeze([...explicitMatches, ...todoMatches, ...negativeMatches]);
+
+	if (negativeMatches.length > 0) {
+		return Object.freeze({
+			isComplete: false,
+			confidence: clampConfidence(0.2 + negativeMatches.length * 0.05),
+			signals,
+		});
+	}
+
+	if (explicitMatches.length === 0 && todoMatches.length === 0) {
+		return Object.freeze({
+			isComplete: false,
+			confidence: 0,
+			signals,
+		});
+	}
+
+	const explicitConfidence =
+		explicitMatches.length > 0 ? 0.75 + (explicitMatches.length - 1) * 0.1 : 0;
+	const todoConfidence = todoMatches.length > 0 ? 0.65 + (todoMatches.length - 1) * 0.1 : 0;
+	const combinedBonus = explicitMatches.length > 0 && todoMatches.length > 0 ? 0.1 : 0;
+
+	return Object.freeze({
+		isComplete: true,
+		confidence: clampConfidence(Math.max(explicitConfidence, todoConfidence) + combinedBonus),
+		signals,
+	});
+}

package/src/autonomy/controller.ts

@@ -0,0 +1,144 @@
+import { getLogger } from "../logging/domains";
+import type { Logger } from "../logging/types";
+import { detectCompletion } from "./completion";
+import { LoopStateMachine } from "./state";
+import type { LoopContext, LoopOptions } from "./types";
+import { VerificationHandler } from "./verification";
+
+export interface LoopControllerConfig {
+	readonly maxIterations?: number;
+	readonly verifyOnComplete?: boolean;
+	readonly cooldownMs?: number;
+	readonly logger?: Logger;
+	readonly verificationHandler?: VerificationHandler;
+}
+
+function delay(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function summarizeFailedChecks(context: LoopContext): string {
+	const latestResult = context.verificationResults[context.verificationResults.length - 1];
+	if (!latestResult) {
+		return "Verification failed.";
+	}
+
+	const failedChecks = latestResult.checks
+		.filter((check) => !check.passed)
+		.map((check) => `${check.name}: ${check.message}`);
+
+	return failedChecks.length > 0
+		? `Verification failed: ${failedChecks.join("; ")}`
+		: "Verification failed.";
+}
+
+export class LoopController {
+	private machine: LoopStateMachine;
+	private paused = false;
+	private maxIterations: number;
+	private verifyOnComplete: boolean;
+	private cooldownMs: number;
+	private readonly logger: Logger;
+	private readonly verificationHandler: VerificationHandler;
+
+	constructor(config: LoopControllerConfig = {}) {
+		this.maxIterations = config.maxIterations ?? 10;
+		this.verifyOnComplete = config.verifyOnComplete ?? true;
+		this.cooldownMs = config.cooldownMs ?? 0;
+		this.logger = config.logger ?? getLogger("autonomy", "controller");
+		this.verificationHandler = config.verificationHandler ?? new VerificationHandler();
+		this.machine = new LoopStateMachine(this.maxIterations);
+	}
+
+	start(taskDescription: string, options: LoopOptions = {}): LoopContext {
+		this.maxIterations = options.maxIterations ?? this.maxIterations;
+		this.verifyOnComplete = options.verifyOnComplete ?? this.verifyOnComplete;
+		this.cooldownMs = options.cooldownMs ?? this.cooldownMs;
+		this.paused = false;
+		this.machine = new LoopStateMachine(this.maxIterations, taskDescription);
+		this.machine.transition("running");
+		this.logger.info("Autonomy loop started", {
+			operation: "start",
+			taskDescription,
+			maxIterations: this.machine.getContext().maxIterations,
+		});
+		return this.machine.getContext();
+	}
+
+	async iterate(iterationResult: string): Promise<LoopContext> {
+		const status = this.machine.getContext();
+		if (this.paused || status.state !== "running") {
+			return status;
+		}
+
+		this.machine.addContext(iterationResult);
+		const exceeded = this.machine.incrementIteration();
+		if (exceeded) {
+			this.machine.transition("max_iterations");
+			this.logger.warn("Autonomy loop hit max iterations", {
+				operation: "iterate",
+				currentIteration: this.machine.getContext().currentIteration,
+			});
+			return this.machine.getContext();
+		}
+
+		const completion = detectCompletion(this.machine.getContext().accumulatedContext);
+		if (!completion.isComplete) {
+			await this.applyCooldown();
+			return this.machine.getContext();
+		}
+
+		if (!this.verifyOnComplete) {
+			this.machine.transition("complete");
+			return this.machine.getContext();
+		}
+
+		this.machine.transition("verifying");
+		const verificationResult = await this.verificationHandler.verify(this.machine.getContext());
+		this.machine.addVerificationResult(verificationResult);
+
+		if (verificationResult.passed) {
+			this.machine.transition("complete");
+			return this.machine.getContext();
+		}
+
+		this.machine.transition("running");
+		this.machine.addContext(summarizeFailedChecks(this.machine.getContext()));
+		await this.applyCooldown();
+		return this.machine.getContext();
+	}
+
+	pause(): LoopContext {
+		this.paused = true;
+		return this.machine.getContext();
+	}
+
+	resume(): LoopContext {
+		this.paused = false;
+		return this.machine.getContext();
+	}
+
+	abort(): LoopContext {
+		const status = this.machine.getContext();
+		if (status.state === "running" || status.state === "verifying") {
+			this.machine.transition("failed");
+			this.machine.addContext("Loop aborted by operator.");
+			this.logger.warn("Autonomy loop aborted", { operation: "abort" });
+		}
+		return this.machine.getContext();
+	}
+
+	getStatus(): LoopContext {
+		return this.machine.getContext();
+	}
+
+	isComplete(): boolean {
+		return this.machine.getContext().state === "complete";
+	}
+
+	private async applyCooldown(): Promise<void> {
+		if (this.cooldownMs > 0) {
+			await delay(this.cooldownMs);
+		}
+	}
+}

package/src/autonomy/index.ts

@@ -0,0 +1,25 @@
+import { getLogger } from "../logging/domains";
+import { LoopController } from "./controller";
+
+let globalLoopController: LoopController | null = null;
+
+export function getLoopController(): LoopController {
+	if (!globalLoopController) {
+		globalLoopController = new LoopController({
+			logger: getLogger("autonomy", "controller"),
+		});
+	}
+
+	return globalLoopController;
+}
+
+export function setLoopControllerForTests(controller: LoopController | null): void {
+	globalLoopController = controller;
+}
+
+export * from "./completion";
+export * from "./controller";
+export * from "./injector";
+export * from "./state";
+export * from "./types";
+export * from "./verification";

package/src/autonomy/injector.ts

@@ -0,0 +1,49 @@
+import type { LoopController } from "./controller";
+
+const LOOP_CONTEXT_CHAR_BUDGET = 500;
+
+interface LoopInjectorInput {
+	readonly sessionID?: string;
+}
+
+interface LoopInjectorOutput {
+	system: string[];
+}
+
+function truncate(value: string, maxLength: number): string {
+	if (value.length <= maxLength) {
+		return value;
+	}
+
+	return `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+
+function buildLoopContext(controller: LoopController): string {
+	const status = controller.getStatus();
+	const remainingIterations = Math.max(0, status.maxIterations - status.currentIteration);
+	const lastContext = status.accumulatedContext[status.accumulatedContext.length - 1] ?? "None";
+	const baseContext = [
+		"[Autonomy Loop]",
+		`State: ${status.state}`,
+		`Current iteration: ${status.currentIteration} of ${status.maxIterations}`,
+		`Remaining iterations: ${remainingIterations}`,
+		`Last context: ${lastContext}`,
+	].join("\n");
+
+	return truncate(baseContext, LOOP_CONTEXT_CHAR_BUDGET);
+}
+
+export function createLoopInjector(controller: LoopController) {
+	return async (_input: LoopInjectorInput, output: LoopInjectorOutput): Promise<void> => {
+		if (controller.getStatus().state === "idle") {
+			return;
+		}
+
+		const loopContext = buildLoopContext(controller);
+		output.system.push(loopContext);
+	};
+}
+
+export const loopInjectorConstants = Object.freeze({
+	LOOP_CONTEXT_CHAR_BUDGET,
+});

package/src/autonomy/state.ts

@@ -0,0 +1,91 @@
+import type { LoopContext, LoopState, VerificationResult } from "./types";
+
+const DEFAULT_MAX_ITERATIONS = 10;
+const HARD_MAX_ITERATIONS = 50;
+
+const VALID_TRANSITIONS = Object.freeze({
+	idle: Object.freeze(["running"] as const),
+	running: Object.freeze(["verifying", "complete", "failed", "max_iterations"] as const),
+	verifying: Object.freeze(["running", "complete", "failed"] as const),
+	complete: Object.freeze([] as const),
+	failed: Object.freeze([] as const),
+	max_iterations: Object.freeze([] as const),
+}) satisfies Readonly<Record<LoopState, readonly LoopState[]>>;
+
+function clampMaxIterations(maxIterations: number): number {
+	return Math.max(1, Math.min(maxIterations, HARD_MAX_ITERATIONS));
+}
+
+function createInitialContext(maxIterations: number): LoopContext {
+	return Object.freeze({
+		taskDescription: "",
+		maxIterations: clampMaxIterations(maxIterations),
+		currentIteration: 0,
+		state: "idle",
+		startedAt: new Date().toISOString(),
+		lastIterationAt: null,
+		accumulatedContext: Object.freeze([]),
+		verificationResults: Object.freeze([]),
+	});
+}
+
+export class LoopStateMachine {
+	private context: LoopContext;
+
+	constructor(maxIterations = DEFAULT_MAX_ITERATIONS, taskDescription = "") {
+		this.context = Object.freeze({
+			...createInitialContext(maxIterations),
+			taskDescription,
+		});
+	}
+
+	transition(to: LoopState): void {
+		const validTargets: readonly LoopState[] = VALID_TRANSITIONS[this.context.state];
+		if (!validTargets.includes(to)) {
+			throw new Error(`Invalid loop state transition: ${this.context.state} -> ${to}`);
+		}
+
+		this.context = Object.freeze({
+			...this.context,
+			state: to,
+		});
+	}
+
+	getContext(): LoopContext {
+		return Object.freeze({
+			...this.context,
+			accumulatedContext: Object.freeze([...this.context.accumulatedContext]),
+			verificationResults: Object.freeze([...this.context.verificationResults]),
+		});
+	}
+
+	incrementIteration(): boolean {
+		const nextIteration = this.context.currentIteration + 1;
+		this.context = Object.freeze({
+			...this.context,
+			currentIteration: nextIteration,
+			lastIterationAt: new Date().toISOString(),
+		});
+
+		return nextIteration > this.context.maxIterations;
+	}
+
+	addContext(text: string): void {
+		this.context = Object.freeze({
+			...this.context,
+			accumulatedContext: Object.freeze([...this.context.accumulatedContext, text]),
+		});
+	}
+
+	addVerificationResult(result: VerificationResult): void {
+		this.context = Object.freeze({
+			...this.context,
+			verificationResults: Object.freeze([...this.context.verificationResults, result]),
+		});
+	}
+}
+
+export const loopStateMachineConstants = Object.freeze({
+	DEFAULT_MAX_ITERATIONS,
+	HARD_MAX_ITERATIONS,
+});

package/src/autonomy/types.ts

@@ -0,0 +1,30 @@
+export type LoopState = "idle" | "running" | "verifying" | "complete" | "failed" | "max_iterations";
+
+export interface LoopContext {
+	readonly taskDescription: string;
+	readonly maxIterations: number;
+	readonly currentIteration: number;
+	readonly state: LoopState;
+	readonly startedAt: string;
+	readonly lastIterationAt: string | null;
+	readonly accumulatedContext: readonly string[];
+	readonly verificationResults: readonly VerificationResult[];
+}
+
+export interface VerificationResult {
+	readonly passed: boolean;
+	readonly checks: readonly VerificationCheck[];
+	readonly timestamp: string;
+}
+
+export interface VerificationCheck {
+	readonly name: string;
+	readonly passed: boolean;
+	readonly message: string;
+}
+
+export interface LoopOptions {
+	readonly maxIterations?: number;
+	readonly verifyOnComplete?: boolean;
+	readonly cooldownMs?: number;
+}