loopgen 0.3.0 → 0.4.0

package/README.md

@@ -160,7 +160,26 @@ npm run loopgen -- run test-repair .
 
 - `--dry-run`:只检查、不写文件。
 - `--base <ref>`:指定对比的 git ref(默认 `HEAD`)。
-- 说明:v1 是**事后检测,而非沙箱阻断**——它证明改动通过了你的真实验证、且没有改动禁止路径。
+- 说明:referee 模式是**事后检测,而非沙箱阻断**——它证明改动通过了你的真实验证、且没有改动禁止路径。
+
+#### driven 模式 —— 让 loopgen 自己跑这个 loop（`--mode driven`）
+
+driven 模式从「事后检测」升级为「过程阻断」:loopgen 驱动一个**本地模型**(Ollama 或任意
+OpenAI-compatible 服务)跑有界的 agent 循环,并**在落盘前强制护栏** —— 写禁止路径会在落盘前被拦,
+不在白名单里的命令不会执行,超过迭代/时间上限就停。
+
+```bash
+npm run loopgen -- run test-repair . --mode driven --adapter ollama --ollama-model qwen2.5-coder
+```
+
+每轮模型给出一小批 JSON 动作(`write_file` / `run_command` / `finish`);loopgen 逐条校验
+(限制在仓库内、拦禁止路径、命令白名单、大小上限),应用允许的动作,跑你的 `verification.commands`,
+再把结果喂回去 —— 直到验证通过、模型 finish、或触达 `maxIterations` / 超时。它写入**同一套**带哈希链的
+审计 + 一份含完整迭代历史(包括每次被拦动作)的证明报告。
+
+- local-first:只调用你配置的本地/自托管模型;API key 只按环境变量名读取,绝不记录或写入文件。
+- 需要干净的 git 工作区(`--allow-dirty` 可跳过);`--dry-run` 只预览第一轮提议、不写文件。
+- 诚实说明:**有界 + 强制 + 验证 + 留证 —— 不是沙箱。** 模型仍会提议,loopgen 负责框住、限制、验证、留证。
 
 可用 adapter：
 
@@ -391,8 +410,31 @@ in `.loopgen/reports/*.md`. The process exits `0` on pass and `1` on fail, so it
 
 - `--dry-run` — run the checks, write nothing.
 - `--base <ref>` — git ref to diff against (default `HEAD`).
-- Scope: v1 is **detection, not a sandbox** — it proves the change passed your real verification and didn't
-  modify forbidden paths; it does not block reads or out-of-tree writes.
+- Scope: referee mode is **detection, not a sandbox** — it proves the change passed your real verification
+  and didn't modify forbidden paths; it does not block reads or out-of-tree writes.
+
+#### Driven mode — loopgen runs the loop (`--mode driven`)
+
+Driven mode goes from *detection* to **prevention**: loopgen drives a **local model** (Ollama or any
+OpenAI-compatible server) through a bounded agentic loop and **enforces guardrails at apply time** — a
+forbidden-path write is blocked *before it lands*, a non-allowlisted command is never run, and the loop
+stops at the iteration/time limit.
+
+```bash
+npm run loopgen -- run test-repair . --mode driven --adapter ollama --ollama-model qwen2.5-coder
+```
+
+Each iteration the model proposes a small JSON action batch (`write_file` / `run_command` / `finish`);
+loopgen validates every action (root-confined, forbidden paths blocked, command allowlist, size caps),
+applies the allowed ones, runs your `verification.commands`, and feeds the result back — until verification
+passes, the model finishes, or it hits `maxIterations` / the timeout. It writes the **same** hash-chained
+audit + a proof report with the full iteration history (including every blocked attempt).
+
+- Local-first: only your configured local/self-hosted model is called; API keys are read by env-var name
+  only and never logged or stored.
+- Needs a clean git tree (`--allow-dirty` to override); `--dry-run` previews the first proposal without writing.
+- Honest scope: **bounded + enforced + verified + proven — not a sandbox.** The model still proposes; loopgen
+  bounds, confines, verifies, and proves.
 
 Available adapters:
 

package/dist/cli.js

@@ -156,6 +156,14 @@ program
     .option("--json", "print the run result as JSON")
     .option("--dry-run", "run checks without writing audit, report, or state")
     .option("--no-report", "do not write the markdown proof report")
+    .option("--adapter <id>", "driven mode: ollama | openai-compatible")
+    .option("--max-iterations <n>", "driven mode: override the loop's max iterations")
+    .option("--allow-dirty", "driven mode: allow running with a dirty working tree")
+    .option("--ollama-model <model>", "driven mode: Ollama model name")
+    .option("--ollama-base-url <url>", "driven mode: Ollama base URL")
+    .option("--openai-compatible-model <model>", "driven mode: OpenAI-compatible model name")
+    .option("--openai-compatible-base-url <url>", "driven mode: OpenAI-compatible base URL")
+    .option("--openai-compatible-api-key-env <name>", "driven mode: env var name for the API key")
     .description("Run a loop's verification against the working tree and write a tamper-evident proof.")
     .action(async (loop, project, options) => {
     const result = await runLoop({
@@ -165,7 +173,15 @@ program
         base: options.base,
         loopsFile: options.loopsFile,
         dryRun: options.dryRun,
-        writeReport: options.report
+        writeReport: options.report,
+        allowDirty: options.allowDirty,
+        adapter: options.adapter === "openai-compatible" ? "openai-compatible" : options.adapter === "ollama" ? "ollama" : undefined,
+        maxIterations: options.maxIterations ? Number(options.maxIterations) : undefined,
+        ollamaModel: options.ollamaModel,
+        ollamaBaseUrl: options.ollamaBaseUrl,
+        openaiCompatibleModel: options.openaiCompatibleModel,
+        openaiCompatibleBaseUrl: options.openaiCompatibleBaseUrl,
+        openaiCompatibleApiKeyEnv: options.openaiCompatibleApiKeyEnv
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -228,6 +244,10 @@ function printGenerationSummary(result) {
 }
 function printRunResult(result) {
     console.log(`${result.passed ? "PASS" : "FAIL"} — loop ${result.loop.id} (${result.entry.mode}${result.dryRun ? ", dry-run" : ""})`);
+    if (result.entry.driven) {
+        const blocked = result.entry.driven.attempts.reduce((sum, attempt) => sum + attempt.blocked.length, 0);
+        console.log(`  driven: ${result.entry.iterations} iteration(s), stop=${result.entry.driven.stopReason}, blocked=${blocked}`);
+    }
     for (const command of result.verification.results) {
         const mark = command.timedOut ? "timeout" : command.exitCode === 0 ? "ok" : `exit ${command.exitCode}`;
         console.log(`  verify: ${command.command} — ${mark}`);

package/dist/core/agent-loop.js

@@ -0,0 +1,167 @@
+import { applyActions } from "./apply-actions.js";
+import { runVerification } from "./verify.js";
+export async function runDrivenLoop(options) {
+    const { projectRoot, loop, modelClient, timeoutMs, deadline } = options;
+    const system = buildSystemPrompt();
+    const budget = { filesWritten: 0, bytesWritten: 0 };
+    const logs = [];
+    let lastVerification;
+    let prevSignature;
+    let feedback = { blocked: [] };
+    const iterCap = options.dryRun ? 1 : Math.max(options.maxIterations, 1);
+    for (let iteration = 1; iteration <= iterCap; iteration += 1) {
+        if (Date.now() > deadline) {
+            return { passed: false, stopReason: "timeout", iterations: logs, lastVerification };
+        }
+        const messages = [
+            { role: "system", content: system },
+            { role: "user", content: buildUserPrompt(loop, iteration, feedback) }
+        ];
+        const raw = await modelClient.chat(messages);
+        const log = { iteration, reasoning: "", applied: [], blocked: [] };
+        const parsed = parseModelTurn(raw);
+        if (!parsed.ok) {
+            log.parseError = parsed.reason;
+            logs.push(log);
+            feedback = { blocked: [], parseError: parsed.reason };
+            lastVerification = undefined;
+            continue;
+        }
+        const turn = parsed.turn;
+        log.reasoning = turn.reasoning;
+        const hasFinish = turn.actions.some((action) => action.type === "finish");
+        const batch = await applyActions(projectRoot, turn.actions, loop, budget, { timeoutMs, dryRun: options.dryRun });
+        log.applied = batch.applied;
+        log.blocked = batch.blocked;
+        if (options.dryRun) {
+            logs.push(log);
+            return { passed: false, stopReason: "finish", iterations: logs, lastVerification };
+        }
+        const verification = await runVerification(loop.verification.commands, {
+            cwd: projectRoot,
+            timeoutMs,
+            allowedCommands: loop.permissions.allowedCommands
+        });
+        log.verification = verification;
+        logs.push(log);
+        lastVerification = verification;
+        feedback = { verification, blocked: batch.blocked };
+        if (verification.passed) {
+            return { passed: true, stopReason: "verified", iterations: logs, lastVerification };
+        }
+        if (hasFinish) {
+            return { passed: verification.passed, stopReason: "finish", iterations: logs, lastVerification };
+        }
+        const signature = JSON.stringify({ actions: turn.actions, codes: verification.results.map((result) => result.exitCode) });
+        if (signature === prevSignature) {
+            return { passed: false, stopReason: "repeated-failure", iterations: logs, lastVerification };
+        }
+        prevSignature = signature;
+    }
+    return { passed: lastVerification?.passed ?? false, stopReason: "max-iterations", iterations: logs, lastVerification };
+}
+export function parseModelTurn(raw) {
+    const candidates = [raw, stripFences(raw), extractBraced(raw)].filter((value) => Boolean(value));
+    for (const candidate of candidates) {
+        try {
+            const turn = coerceTurn(JSON.parse(candidate));
+            if (turn)
+                return { ok: true, turn };
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return { ok: false, reason: "Response was not valid JSON with an actions array." };
+}
+function coerceTurn(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const object = value;
+    if (!Array.isArray(object.actions))
+        return null;
+    const actions = [];
+    for (const raw of object.actions) {
+        const action = coerceAction(raw);
+        if (action)
+            actions.push(action);
+    }
+    return { reasoning: typeof object.reasoning === "string" ? object.reasoning : "", actions };
+}
+function coerceAction(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const action = value;
+    if (action.type === "write_file" && typeof action.path === "string" && typeof action.content === "string") {
+        return { type: "write_file", path: action.path, content: action.content };
+    }
+    if (action.type === "delete_file" && typeof action.path === "string") {
+        return { type: "delete_file", path: action.path };
+    }
+    if (action.type === "run_command" && typeof action.command === "string") {
+        return { type: "run_command", command: action.command };
+    }
+    if (action.type === "finish") {
+        return { type: "finish", summary: typeof action.summary === "string" ? action.summary : "" };
+    }
+    return null;
+}
+function stripFences(raw) {
+    const match = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    return match ? match[1].trim() : undefined;
+}
+function extractBraced(raw) {
+    const start = raw.indexOf("{");
+    const end = raw.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        return undefined;
+    return raw.slice(start, end + 1);
+}
+function buildSystemPrompt() {
+    return `You are loopgen's bounded maker. You work on a software repository through a strict protocol.
+
+Reply with ONLY a single JSON object, no prose outside it:
+{
+  "reasoning": "one short sentence",
+  "actions": [
+    { "type": "write_file", "path": "relative/path.ext", "content": "full new file contents" },
+    { "type": "delete_file", "path": "relative/path.ext" },
+    { "type": "run_command", "command": "an allowed command" },
+    { "type": "finish", "summary": "why you are done" }
+  ]
+}
+
+Hard rules:
+- Paths must be RELATIVE and inside the repository. Never use absolute paths or "..".
+- Never write to forbidden paths. Only run commands from the allowed list.
+- write_file replaces the entire file with "content". Make the smallest change that satisfies the goal.
+- Emit a "finish" action when verification should pass or you cannot make progress.`;
+}
+function buildUserPrompt(loop, iteration, feedback) {
+    const lines = [];
+    lines.push(`Iteration ${iteration}.`);
+    lines.push(`\nGoal:\n${loop.goal}`);
+    lines.push(`\nAcceptance criteria: ${loop.verification.acceptanceCriteria}`);
+    if (loop.contextSources.length)
+        lines.push(`\nContext sources:\n${loop.contextSources.map((source) => `- ${source}`).join("\n")}`);
+    lines.push(`\nVerification commands (these define success):\n${loop.verification.commands.map((command) => `- ${command}`).join("\n") || "- (none)"}`);
+    lines.push(`\nForbidden paths (writes here are BLOCKED): ${loop.permissions.forbiddenPaths.join(", ") || "(none)"}`);
+    lines.push(`Allowed commands: ${loop.permissions.allowedCommands.join(", ") || "(none — do not use run_command)"}`);
+    if (feedback.parseError) {
+        lines.push(`\nYour previous response was invalid (${feedback.parseError}). Reply with ONLY the JSON object.`);
+    }
+    if (feedback.verification) {
+        const failed = feedback.verification.results.filter((result) => result.exitCode !== 0 || result.timedOut);
+        lines.push(`\nPrevious verification: ${feedback.verification.passed ? "PASSED" : "FAILED"}.`);
+        for (const result of failed) {
+            lines.push(`Command \`${result.command}\` exited ${result.timedOut ? "TIMEOUT" : result.exitCode}:\n${truncate(result.stdoutExcerpt || result.stderrExcerpt, 1500)}`);
+        }
+    }
+    if (feedback.blocked.length) {
+        lines.push(`\nBlocked last turn (do not retry): ${feedback.blocked.map((block) => `${block.type} ${block.target} (${block.reason})`).join("; ")}`);
+    }
+    return lines.join("\n");
+}
+function truncate(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max)}…`;
+}

package/dist/core/apply-actions.js

@@ -0,0 +1,77 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { checkForbiddenPaths } from "./forbidden.js";
+import { runVerification } from "./verify.js";
+export const APPLY_LIMITS = {
+    maxFilesPerRun: 50,
+    maxBytesPerFile: 512 * 1024,
+    maxBytesPerRun: 2 * 1024 * 1024
+};
+// Validate FIRST, mutate SECOND. Forbidden-path writes, path escapes, non-allowlisted commands, and
+// over-budget writes are blocked before anything touches disk — prevention, not just detection.
+export async function applyActions(projectRoot, actions, loop, budget, options) {
+    const root = path.resolve(projectRoot);
+    const applied = [];
+    const blocked = [];
+    const commandResults = [];
+    for (const action of actions) {
+        if (action.type === "finish")
+            continue;
+        if (action.type === "write_file" || action.type === "delete_file") {
+            const rel = toRelative(root, action.path);
+            if (rel === null) {
+                blocked.push({ type: action.type, target: action.path, reason: "path-escape" });
+                continue;
+            }
+            const forbidden = checkForbiddenPaths([rel], loop.permissions.forbiddenPaths);
+            if (!forbidden.ok) {
+                blocked.push({ type: action.type, target: rel, reason: "forbidden-path", pattern: forbidden.violations[0].pattern });
+                continue;
+            }
+            if (action.type === "write_file") {
+                const bytes = Buffer.byteLength(action.content, "utf8");
+                if (bytes > APPLY_LIMITS.maxBytesPerFile ||
+                    budget.filesWritten >= APPLY_LIMITS.maxFilesPerRun ||
+                    budget.bytesWritten + bytes > APPLY_LIMITS.maxBytesPerRun) {
+                    blocked.push({ type: action.type, target: rel, reason: "limit-exceeded" });
+                    continue;
+                }
+                if (!options.dryRun) {
+                    const absolute = path.join(root, rel);
+                    await fs.mkdir(path.dirname(absolute), { recursive: true });
+                    await fs.writeFile(absolute, action.content, "utf8");
+                }
+                budget.filesWritten += 1;
+                budget.bytesWritten += bytes;
+            }
+            else if (!options.dryRun) {
+                await fs.rm(path.join(root, rel), { force: true }).catch(() => undefined);
+            }
+            applied.push({ type: action.type, target: rel });
+            continue;
+        }
+        // run_command — only exact matches of the loop's allowed commands may execute.
+        if (!loop.permissions.allowedCommands.includes(action.command)) {
+            blocked.push({ type: "run_command", target: action.command, reason: "command-not-allowed" });
+            continue;
+        }
+        if (!options.dryRun) {
+            const result = await runVerification([action.command], { cwd: root, timeoutMs: options.timeoutMs });
+            commandResults.push(...result.results);
+        }
+        applied.push({ type: "run_command", target: action.command });
+    }
+    return { applied, blocked, commandResults };
+}
+function toRelative(root, candidate) {
+    if (typeof candidate !== "string" || candidate.length === 0)
+        return null;
+    if (path.isAbsolute(candidate))
+        return null;
+    if (candidate.split(/[\\/]/).includes(".."))
+        return null;
+    const resolved = path.resolve(root, candidate);
+    if (resolved !== root && !resolved.startsWith(root + path.sep))
+        return null;
+    return path.relative(root, resolved).replace(/\\/g, "/");
+}

package/dist/core/audit.js

@@ -3,14 +3,18 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 export const AUDIT_FILE = ".loopgen/audit.jsonl";
 // Deterministic JSON: object keys sorted recursively so the hash is stable across runs/machines.
+// undefined-valued keys are skipped (matching JSON.stringify) so the in-memory hash equals the hash
+// recomputed from the JSON-round-tripped entry — otherwise dropped keys would break the chain.
 function canonicalize(value) {
     if (value === null || typeof value !== "object")
         return JSON.stringify(value);
     if (Array.isArray(value))
         return `[${value.map(canonicalize).join(",")}]`;
-    const entries = Object.keys(value)
+    const record = value;
+    const entries = Object.keys(record)
+        .filter((key) => record[key] !== undefined)
         .sort()
-        .map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`);
+        .map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`);
     return `{${entries.join(",")}}`;
 }
 export function hashEntry(input, prevHash) {

package/dist/core/git.js

@@ -36,6 +36,17 @@ export async function isClean(root) {
     const { stdout } = await git(root, ["status", "--porcelain"]);
     return stdout.trim().length === 0;
 }
+// Changed paths from `git status --porcelain`, excluding loopgen's own output (.loopgen/).
+// Used as the driven-mode precondition so a prior `loopgen apply` doesn't count as a dirty tree.
+export async function dirtyPathsOutsideLoopgen(root) {
+    const { stdout } = await git(root, ["status", "--porcelain"]);
+    return stdout
+        .split("\n")
+        .map((line) => line.slice(3).trim())
+        .map((entry) => (entry.includes(" -> ") ? entry.split(" -> ")[1].trim() : entry))
+        .filter(Boolean)
+        .filter((file) => !file.replace(/\\/g, "/").startsWith(".loopgen/"));
+}
 export async function changedFiles(root, base) {
     const hasCommits = (await headSha(root)) !== null;
     const tracked = hasCommits

package/dist/core/model-client.js

@@ -0,0 +1,63 @@
+export function createModelClient(config) {
+    return config.adapterId === "ollama" ? new OllamaClient(config) : new OpenAiCompatibleClient(config);
+}
+class HttpModelClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async post(url, body, headers) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        let response;
+        try {
+            response = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", ...headers },
+                body: JSON.stringify(body),
+                signal: controller.signal
+            });
+        }
+        catch (error) {
+            throw connectionError(this.config.baseUrl, error);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            throw new Error(`Local model returned HTTP ${response.status} from ${this.config.baseUrl}`);
+        }
+        return response.json();
+    }
+    authHeader() {
+        if (!this.config.apiKeyEnv)
+            return {};
+        const value = process.env[this.config.apiKeyEnv];
+        if (!value) {
+            throw new Error(`Environment variable ${this.config.apiKeyEnv} is not set (needed for the local model API key).`);
+        }
+        return { Authorization: `Bearer ${value}` };
+    }
+}
+class OllamaClient extends HttpModelClient {
+    async chat(messages) {
+        const json = (await this.post(`${trimSlash(this.config.baseUrl)}/api/chat`, { model: this.config.model, stream: false, format: "json", messages }, {}));
+        return json.message?.content ?? "";
+    }
+}
+class OpenAiCompatibleClient extends HttpModelClient {
+    async chat(messages) {
+        const json = (await this.post(`${trimSlash(this.config.baseUrl)}/chat/completions`, { model: this.config.model, messages, response_format: { type: "json_object" } }, this.authHeader()));
+        return json.choices?.[0]?.message?.content ?? "";
+    }
+}
+function trimSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+function connectionError(baseUrl, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    if (/abort/i.test(reason)) {
+        return new Error(`Local model request to ${baseUrl} timed out.`);
+    }
+    return new Error(`Could not reach the local model at ${baseUrl} (is Ollama or your server running?).`);
+}

package/dist/core/model-config.js

@@ -0,0 +1,39 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ADAPTER_PRESETS } from "./adapters.js";
+const MODEL_TIMEOUT_MS = 180_000;
+// Precedence: CLI flags ▸ .loopgen/adapters/<id>/config.json ▸ defaults.
+export async function resolveModelConfig(projectRoot, options) {
+    const adapterId = options.adapter ?? "ollama";
+    const fileConfig = await readAdapterConfig(projectRoot, adapterId);
+    if (adapterId === "ollama") {
+        const baseUrl = options.ollamaBaseUrl?.trim() || fileConfig?.baseUrl?.trim() || ADAPTER_PRESETS.ollama.baseUrl;
+        const model = options.ollamaModel?.trim() || fileConfig?.model?.trim() || "";
+        assertModel(adapterId, model);
+        return { adapterId, baseUrl, model, timeoutMs: MODEL_TIMEOUT_MS };
+    }
+    const baseUrl = options.openaiCompatibleBaseUrl?.trim() || fileConfig?.baseUrl?.trim() || ADAPTER_PRESETS["lm-studio"].baseUrl;
+    const model = options.openaiCompatibleModel?.trim() || fileConfig?.model?.trim() || "";
+    const apiKeyEnv = options.openaiCompatibleApiKeyEnv?.trim() || fileConfig?.apiKeyEnv?.trim() || undefined;
+    assertModel(adapterId, model);
+    return { adapterId, baseUrl, model, apiKeyEnv, timeoutMs: MODEL_TIMEOUT_MS };
+}
+async function readAdapterConfig(projectRoot, adapterId) {
+    const filePath = path.join(projectRoot, ".loopgen", "adapters", adapterId, "config.json");
+    const raw = await fs.readFile(filePath, "utf8").catch(() => undefined);
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return { baseUrl: parsed.baseUrl, model: parsed.model, apiKeyEnv: parsed.apiKeyEnv };
+    }
+    catch {
+        return undefined;
+    }
+}
+function assertModel(adapterId, model) {
+    if (!model || model === "TODO_MODEL") {
+        const flag = adapterId === "ollama" ? "--ollama-model" : "--openai-compatible-model";
+        throw new Error(`No model configured for ${adapterId}. Pass ${flag} <name> or set it in .loopgen/adapters/${adapterId}/config.json.`);
+    }
+}

package/dist/core/report.js

@@ -1,4 +1,4 @@
-export function renderProofReport(loop, entry, verification) {
+export function renderProofReport(loop, entry, verification, iterationLogs) {
     const banner = entry.passed ? "✅ PASS" : "❌ FAIL";
     const changed = [...entry.changedFiles.tracked, ...entry.changedFiles.untracked];
     const commandBlocks = verification.results
@@ -48,11 +48,36 @@ ${verification.warnings.length ? `\n> Warnings:\n${verification.warnings.map((wa
 ## Forbidden paths — ${entry.forbidden.ok ? "clean" : "VIOLATION"}
 
 ${forbiddenSection}
-
+${entry.driven && iterationLogs ? `\n${renderIterationHistory(iterationLogs)}` : ""}
 ---
 
-> Scope: this is **detection, not prevention**. loopgen ran the verification commands above and diffed the
-> working tree after the work session; it does not sandbox the agent or block reads. The audit entry is
-> hash-chained in \`.loopgen/audit.jsonl\` (tamper-evident against in-place edits).
+${scopeFooter(entry)}
 `;
 }
+function renderIterationHistory(iterationLogs) {
+    const blocks = iterationLogs.map((log) => {
+        const applied = log.applied.length ? log.applied.map((action) => `${action.type} \`${action.target}\``).join(", ") : "(none)";
+        const blocked = log.blocked.length
+            ? log.blocked.map((block) => `${block.type} \`${block.target}\` — **blocked** (${block.reason}${block.pattern ? ` \`${block.pattern}\`` : ""})`).join("\n  - ")
+            : "(none)";
+        const verify = log.parseError
+            ? `parse error: ${log.parseError}`
+            : log.verification
+                ? log.verification.passed
+                    ? "verification passed"
+                    : "verification failed"
+                : "no verification";
+        return `### Iteration ${log.iteration}
+
+${log.reasoning ? `> ${log.reasoning}\n` : ""}- Applied: ${applied}
+- Blocked: ${blocked}
+- ${verify}`;
+    });
+    return `## Iteration history\n\n${blocks.join("\n\n")}\n`;
+}
+function scopeFooter(entry) {
+    if (entry.driven) {
+        return `> Scope: **bounded + enforced**. loopgen drove a local model (${entry.driven.model.adapter} · ${entry.driven.model.modelName}), blocked forbidden writes and non-allowlisted commands **at apply time**, bounded iterations, and verified each one (stop reason: ${entry.driven.stopReason}). The model still proposes actions — this is enforcement, not a sandbox. Audit is hash-chained in \`.loopgen/audit.jsonl\`.`;
+    }
+    return `> Scope: this is **detection, not prevention**. loopgen ran the verification commands above and diffed the working tree after the work session; it does not sandbox the agent or block reads. The audit entry is hash-chained in \`.loopgen/audit.jsonl\` (tamper-evident against in-place edits).`;
+}

package/dist/core/runner.js

@@ -2,23 +2,28 @@ import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { runDrivenLoop } from "./agent-loop.js";
 import { appendAuditEntry, hashEntry, readAuditLog } from "./audit.js";
 import { checkForbiddenPaths } from "./forbidden.js";
 import * as git from "./git.js";
 import { loadLoopFile, selectLoop } from "./loop-file.js";
+import { createModelClient } from "./model-client.js";
+import { resolveModelConfig } from "./model-config.js";
 import { renderProofReport } from "./report.js";
 import { runVerification } from "./verify.js";
 export async function runLoop(options) {
     const projectRoot = path.resolve(options.projectRoot);
     const mode = options.mode ?? "referee";
-    if (mode === "driven") {
-        throw new Error("Driven mode is not implemented yet (v2). Use --mode referee.");
-    }
     if (!(await git.isGitRepo(projectRoot))) {
-        throw new Error("loopgen run requires a git repository — referee mode diffs the working tree against a base ref.");
+        throw new Error("loopgen run requires a git repository — it diffs the working tree against a base ref.");
     }
     const loopFile = await loadLoopFile(projectRoot, options.loopsFile);
     const loop = selectLoop(loopFile, options.loopId);
+    return mode === "driven"
+        ? runDriven(projectRoot, loop, loopFile, options)
+        : runReferee(projectRoot, loop, loopFile, options);
+}
+async function runReferee(projectRoot, loop, loopFile, options) {
     const base = options.base ?? "HEAD";
     const shaBefore = await git.headSha(projectRoot, base);
     const clean = await git.isClean(projectRoot);
@@ -27,14 +32,53 @@ export async function runLoop(options) {
     const shaAfter = await git.headSha(projectRoot, "HEAD");
     const allChanged = [...changed.tracked, ...changed.untracked];
     const forbidden = checkForbiddenPaths(allChanged, loop.permissions.forbiddenPaths);
-    const timeoutMs = Math.max(loop.stopCriteria.timeoutMinutes || 1, 1) * 60_000;
+    const timeoutMs = commandTimeoutMs(loop);
     const verification = await runVerification(loop.verification.commands, {
         cwd: projectRoot,
         timeoutMs,
         allowedCommands: loop.permissions.allowedCommands
     });
     const passed = verification.passed && forbidden.ok;
-    const input = {
+    const input = baseEntry(loopFile, loop, "referee", { base, shaBefore, shaAfter, clean }, changed, diffstat, forbidden, verification, 1, passed);
+    return finalize(projectRoot, loop, input, verification, forbidden, options);
+}
+async function runDriven(projectRoot, loop, loopFile, options) {
+    if (!options.dryRun && !options.allowDirty) {
+        const dirty = await git.dirtyPathsOutsideLoopgen(projectRoot);
+        if (dirty.length) {
+            throw new Error("Working tree is dirty. Driven mode edits files — commit/stash first, or pass --allow-dirty.");
+        }
+    }
+    const modelClient = options.modelClient ?? createModelClient(await resolveModelConfig(projectRoot, options));
+    const modelMeta = options.modelClient
+        ? { adapter: "injected", modelName: "injected", baseUrl: "test" }
+        : await modelMetaFromConfig(projectRoot, options);
+    const base = options.base ?? "HEAD";
+    const shaBefore = await git.headSha(projectRoot, base);
+    const clean = await git.isClean(projectRoot);
+    const timeoutMs = commandTimeoutMs(loop);
+    const maxIterations = options.maxIterations ?? loop.stopCriteria.maxIterations;
+    const driven = await runDrivenLoop({
+        projectRoot,
+        loop,
+        modelClient,
+        maxIterations,
+        timeoutMs,
+        deadline: Date.now() + timeoutMs,
+        dryRun: options.dryRun
+    });
+    const changed = await git.changedFiles(projectRoot, base);
+    const diffstat = await git.diffStat(projectRoot, base);
+    const shaAfter = await git.headSha(projectRoot, "HEAD");
+    const forbidden = checkForbiddenPaths([...changed.tracked, ...changed.untracked], loop.permissions.forbiddenPaths);
+    const verification = driven.lastVerification ?? { passed: false, results: [], warnings: [] };
+    const passed = driven.passed && forbidden.ok;
+    const input = baseEntry(loopFile, loop, "driven", { base, shaBefore, shaAfter, clean }, changed, diffstat, forbidden, verification, driven.iterations.length, passed);
+    input.driven = { stopReason: driven.stopReason, model: modelMeta, attempts: summarizeIterations(driven.iterations) };
+    return finalize(projectRoot, loop, input, verification, forbidden, options, driven.iterations);
+}
+function baseEntry(loopFile, loop, mode, gitInfo, changed, diffstat, forbidden, verification, iterations, passed) {
+    return {
         schemaVersion: "1",
         entryId: randomUUID(),
         timestamp: new Date().toISOString(),
@@ -42,7 +86,7 @@ export async function runLoop(options) {
         loopId: loop.id,
         mode,
         actor: { user: safe(() => os.userInfo().username), host: safe(() => os.hostname()) },
-        git: { base, shaBefore, shaAfter, clean },
+        git: gitInfo,
         changedFiles: { tracked: changed.tracked, untracked: changed.untracked, diffstat },
         forbidden: { ok: forbidden.ok, violations: forbidden.violations },
         verification: {
@@ -54,9 +98,11 @@ export async function runLoop(options) {
                 durationMs: result.durationMs
             }))
         },
-        iterations: 1,
+        iterations,
         passed
     };
+}
+async function finalize(projectRoot, loop, input, verification, forbidden, options, iterationLogs) {
     let entry;
     if (options.dryRun) {
         const existing = await readAuditLog(projectRoot);
@@ -72,18 +118,48 @@ export async function runLoop(options) {
         reportPath = path.join(".loopgen", "reports", `${loop.id}-${stamp}.md`);
         const absolute = path.join(projectRoot, reportPath);
         await fs.mkdir(path.dirname(absolute), { recursive: true });
-        await fs.writeFile(absolute, renderProofReport(loop, entry, verification), "utf8");
+        await fs.writeFile(absolute, renderProofReport(loop, entry, verification, iterationLogs), "utf8");
     }
     if (!options.dryRun) {
         await appendStateEntry(projectRoot, loop, entry);
     }
-    return { loop, passed, entry, verification, forbidden, reportPath, dryRun: Boolean(options.dryRun) };
+    return {
+        loop,
+        passed: entry.passed,
+        entry,
+        verification,
+        forbidden,
+        reportPath,
+        dryRun: Boolean(options.dryRun),
+        iterationLogs
+    };
+}
+function summarizeIterations(logs) {
+    return logs.map((log) => ({
+        iteration: log.iteration,
+        actions: {
+            write: log.applied.filter((action) => action.type === "write_file").length,
+            delete: log.applied.filter((action) => action.type === "delete_file").length,
+            run: log.applied.filter((action) => action.type === "run_command").length,
+            finish: 0
+        },
+        blocked: log.blocked.map((block) => ({ type: block.type, reason: block.reason, pattern: block.pattern })),
+        verificationPassed: log.verification?.passed ?? false,
+        parseError: log.parseError
+    }));
+}
+async function modelMetaFromConfig(projectRoot, options) {
+    const config = await resolveModelConfig(projectRoot, options);
+    return { adapter: config.adapterId, modelName: config.model, baseUrl: config.baseUrl };
+}
+function commandTimeoutMs(loop) {
+    return Math.max(loop.stopCriteria.timeoutMinutes || 1, 1) * 60_000;
 }
 async function appendStateEntry(projectRoot, loop, entry) {
     const stateFile = loop.stateFile || path.join(".loopgen", "state", `${loop.id}.md`);
     const absolute = path.join(projectRoot, stateFile);
     const passedCount = entry.verification.commands.filter((command) => command.exitCode === 0 && !command.timedOut).length;
-    const line = `- ${entry.timestamp} — ${entry.passed ? "PASS" : "FAIL"} — iter ${entry.iterations} — verification ${passedCount}/${entry.verification.commands.length} — forbidden ${entry.forbidden.ok ? "ok" : `${entry.forbidden.violations.length} violation(s)`} — audit ${entry.entryId}`;
+    const line = `- ${entry.timestamp} — ${entry.passed ? "PASS" : "FAIL"} — ${entry.mode} — iter ${entry.iterations} — verification ${passedCount}/${entry.verification.commands.length} — forbidden ${entry.forbidden.ok ? "ok" : `${entry.forbidden.violations.length} violation(s)`} — audit ${entry.entryId}`;
     const existing = await fs.readFile(absolute, "utf8").catch(() => undefined);
     let next;
     if (existing && existing.includes("- No attempts yet.")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopgen",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Generate bounded, verifiable AI agent configs for Codex, Claude, Cursor, and local models — with safety rails baked in.",
   "type": "module",
   "engines": {