loopgen 0.2.1 → 0.4.0

package/README.md

@@ -139,10 +139,48 @@ npm run loopgen -- preview [project] --templates all --adapters codex,claude
 npm run loopgen -- preview [project] --templates test-repair --adapters ollama --ollama-model llama3.1
 npm run loopgen -- preview [project] --templates test-repair --adapters openai-compatible --openai-compatible-model qwen2.5-coder
 npm run loopgen -- apply [project] --templates all --adapters codex,claude
+npm run loopgen -- run [loop] [project]
 ```
 
 `apply` 会先展示 diff。没有 `--yes` 时，它会要求你确认后才写入文件。
 
+### 运行并验证（loopgen run）
+
+生成配置只是说明，**`loopgen run` 会真正执行验证并留下证据** —— 这是模型本身做不到的。
+在用任意 agent（Claude Code、Cursor、Codex 等）完成一段有界的改动后,运行:
+
+```bash
+npm run loopgen -- run test-repair .
+```
+
+它会:对照 git 跑出本次改动 → 执行该 loop 的 `verification.commands` 并按退出码判定通过/失败 →
+检查是否动了 `forbiddenPaths`(如 `.env`)→ 写入一条**带哈希链、防篡改**的审计记录
+`.loopgen/audit.jsonl`,以及一份可读的「证明报告」`.loopgen/reports/*.md`。通过则进程退出码为 0,
+失败为 1(便于接入 CI / git hook)。
+
+- `--dry-run`:只检查、不写文件。
+- `--base <ref>`:指定对比的 git ref(默认 `HEAD`)。
+- 说明: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：
 
 - `agents-md`：通用 `AGENTS.md`，可被 Claude Code、Codex、Cursor、Copilot、Gemini CLI、Aider 等读取
@@ -350,10 +388,54 @@ npm run loopgen -- preview [project] --templates all --adapters codex,claude
 npm run loopgen -- preview [project] --templates test-repair --adapters ollama --ollama-model llama3.1
 npm run loopgen -- preview [project] --templates test-repair --adapters openai-compatible --openai-compatible-model qwen2.5-coder
 npm run loopgen -- apply [project] --templates all --adapters codex,claude
+npm run loopgen -- run [loop] [project]
 ```
 
 `apply` always shows a diff first. Without `--yes`, it asks for confirmation before writing files.
 
+### Run & prove the work (`loopgen run`)
+
+Generating config is just instructions. **`loopgen run` actually runs the verification and leaves proof** —
+something a stateless model cannot do. After you (or any agent — Claude Code, Cursor, Codex) complete a
+bounded change, run:
+
+```bash
+npm run loopgen -- run test-repair .
+```
+
+It diffs your working tree against git, executes the loop's `verification.commands` and gates pass/fail on
+the real exit codes, checks whether any `forbiddenPaths` (e.g. `.env`) were touched, and writes a
+**tamper-evident, hash-chained audit record** to `.loopgen/audit.jsonl` plus a human-readable proof report
+in `.loopgen/reports/*.md`. The process exits `0` on pass and `1` on fail, so it composes into CI / git hooks.
+
+- `--dry-run` — run the checks, write nothing.
+- `--base <ref>` — git ref to diff against (default `HEAD`).
+- 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:
 
 - `agents-md` — one `AGENTS.md` read by Claude Code, Codex, Cursor, Copilot, Gemini CLI, Aider, and more

package/dist/cli.js

@@ -12,6 +12,7 @@ import { scanProject } from "./core/scanner.js";
 import { TEMPLATE_DEFINITIONS } from "./core/templates.js";
 import { startLoopgenServer } from "./server.js";
 import { DEFAULT_ADAPTER_IDS, parseAdapterIds } from "./core/adapters.js";
+import { runLoop } from "./core/runner.js";
 const PROJECT_MANIFESTS = [
     "package.json",
     "pyproject.toml",
@@ -145,6 +146,51 @@ program
     const written = await applyGeneratedFiles(result.scan.root, result.files);
     console.log(`Wrote ${written.length} files.`);
 });
+program
+    .command("run")
+    .argument("[loop]", "loop id from .loopgen/loopgen.loop.yaml")
+    .argument("[project]", "project directory", ".")
+    .option("--mode <mode>", "referee | driven", "referee")
+    .option("--base <ref>", "git ref to diff the working tree against", "HEAD")
+    .option("--loops-file <path>", "path to the loop file")
+    .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({
+        projectRoot: path.resolve(project),
+        loopId: loop,
+        mode: options.mode ?? "referee",
+        base: options.base,
+        loopsFile: options.loopsFile,
+        dryRun: options.dryRun,
+        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));
+    }
+    else {
+        printRunResult(result);
+    }
+    process.exitCode = result.passed ? 0 : 1;
+});
 program.parseAsync(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
@@ -196,6 +242,29 @@ function printGenerationSummary(result) {
         console.warn(`Warning: ${warning}`);
     }
 }
+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}`);
+    }
+    if (!result.verification.results.length) {
+        console.log("  verify: no verification commands configured for this loop");
+    }
+    for (const violation of result.forbidden.violations) {
+        console.log(`  forbidden: ${violation.file} (matched ${violation.pattern})`);
+    }
+    const changed = result.entry.changedFiles.tracked.length + result.entry.changedFiles.untracked.length;
+    console.log(`  files changed: ${changed}`);
+    if (result.reportPath)
+        console.log(`  report: ${result.reportPath}`);
+    if (!result.dryRun)
+        console.log(`  audit: .loopgen/audit.jsonl (${result.entry.hash.slice(0, 12)}…)`);
+}
 function formatCommands(commands) {
     const entries = Object.entries(commands).filter(([, command]) => command);
     return entries.length ? entries.map(([name, command]) => `${name}=${command}`).join(", ") : "none inferred";

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

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+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 record = value;
+    const entries = Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`);
+    return `{${entries.join(",")}}`;
+}
+export function hashEntry(input, prevHash) {
+    return createHash("sha256").update(canonicalize({ ...input, prevHash })).digest("hex");
+}
+async function readRaw(projectRoot) {
+    return fs.readFile(path.join(projectRoot, AUDIT_FILE), "utf8").catch(() => undefined);
+}
+export async function readAuditLog(projectRoot) {
+    const raw = await readRaw(projectRoot);
+    if (!raw)
+        return [];
+    return raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export async function appendAuditEntry(projectRoot, input) {
+    const existing = await readAuditLog(projectRoot);
+    const prevHash = existing.length ? existing[existing.length - 1].hash : null;
+    const entry = { ...input, prevHash, hash: hashEntry(input, prevHash) };
+    const filePath = path.join(projectRoot, AUDIT_FILE);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+    return entry;
+}
+export function verifyAuditChain(entries) {
+    let prevHash = null;
+    for (let index = 0; index < entries.length; index += 1) {
+        const { hash, prevHash: storedPrev, ...input } = entries[index];
+        if (storedPrev !== prevHash)
+            return { valid: false, brokenAt: index };
+        if (hashEntry(input, storedPrev) !== hash)
+            return { valid: false, brokenAt: index };
+        prevHash = hash;
+    }
+    return { valid: true };
+}

package/dist/core/forbidden.js

@@ -0,0 +1,38 @@
+// Translate the loop's glob-ish forbidden patterns (e.g. ".env", ".env.*", "secrets/**",
+// "**/*credential*") into anchored RegExps. No glob dependency is needed for these patterns.
+export function globToRegExp(pattern) {
+    let regex = "";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        if (char === "*") {
+            if (pattern[index + 1] === "*") {
+                regex += ".*"; // ** crosses path separators
+                index += 1;
+            }
+            else {
+                regex += "[^/]*"; // * stays within a path segment
+            }
+        }
+        else if (char === "?") {
+            regex += "[^/]";
+        }
+        else {
+            regex += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${regex}$`);
+}
+export function checkForbiddenPaths(changed, forbiddenPaths) {
+    const matchers = forbiddenPaths.map((pattern) => ({ pattern, regex: globToRegExp(pattern) }));
+    const violations = [];
+    for (const file of changed) {
+        const normalized = file.replace(/\\/g, "/");
+        for (const matcher of matchers) {
+            if (matcher.regex.test(normalized)) {
+                violations.push({ file: normalized, pattern: matcher.pattern });
+                break;
+            }
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}

package/dist/core/git.js

@@ -0,0 +1,69 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function git(root, args) {
+    try {
+        const { stdout } = await execFileAsync("git", args, { cwd: root, maxBuffer: 32 * 1024 * 1024 });
+        return { stdout, code: 0 };
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error) {
+            const code = error.code;
+            const stdout = String(error.stdout ?? "");
+            if (typeof code === "number")
+                return { stdout, code };
+        }
+        throw error;
+    }
+}
+export async function isGitRepo(root) {
+    try {
+        const { stdout, code } = await git(root, ["rev-parse", "--is-inside-work-tree"]);
+        return code === 0 && stdout.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+export async function headSha(root, ref = "HEAD") {
+    const { stdout, code } = await git(root, ["rev-parse", ref]);
+    if (code !== 0)
+        return null;
+    const sha = stdout.trim();
+    return sha.length ? sha : null;
+}
+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
+        ? splitLines((await git(root, ["diff", "--name-only", base])).stdout)
+        : splitLines((await git(root, ["ls-files"])).stdout);
+    const untracked = splitLines((await git(root, ["ls-files", "--others", "--exclude-standard"])).stdout);
+    return { tracked, untracked };
+}
+export async function diffStat(root, base) {
+    if ((await headSha(root)) === null)
+        return "(no commits yet — diff against empty tree)";
+    const { stdout } = await git(root, ["diff", "--stat", base]);
+    return stdout.trimEnd();
+}
+function splitLines(value) {
+    return value
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+}

package/dist/core/loop-file.js

@@ -0,0 +1,53 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+export const DEFAULT_LOOPS_FILE = ".loopgen/loopgen.loop.yaml";
+export async function loadLoopFile(projectRoot, loopsFile = DEFAULT_LOOPS_FILE) {
+    const filePath = path.join(projectRoot, loopsFile);
+    const raw = await fs.readFile(filePath, "utf8").catch(() => {
+        throw new Error(`No loop file at ${loopsFile}. Run \`loopgen apply\` first to generate it.`);
+    });
+    const parsed = parse(raw);
+    if (!parsed || !Array.isArray(parsed.loops)) {
+        throw new Error(`Malformed loop file at ${loopsFile}: missing a "loops" array.`);
+    }
+    parsed.loops.forEach((loop, index) => assertLoopSpec(loop, index));
+    return {
+        version: typeof parsed.version === "string" ? parsed.version : "unknown",
+        project: typeof parsed.project === "string" ? parsed.project : path.basename(projectRoot),
+        loops: parsed.loops
+    };
+}
+export function selectLoop(loopFile, id) {
+    if (id) {
+        const found = loopFile.loops.find((loop) => loop.id === id);
+        if (!found) {
+            throw new Error(`Unknown loop "${id}". Available: ${loopFile.loops.map((loop) => loop.id).join(", ") || "(none)"}`);
+        }
+        return found;
+    }
+    if (loopFile.loops.length === 1)
+        return loopFile.loops[0];
+    throw new Error(`Multiple loops found — specify one. Available: ${loopFile.loops.map((loop) => loop.id).join(", ")}`);
+}
+// YAML is untrusted at runtime: assert the fields the runner depends on.
+function assertLoopSpec(loop, index) {
+    const where = `loops[${index}]`;
+    if (!loop || typeof loop !== "object")
+        throw new Error(`${where} is not an object.`);
+    const value = loop;
+    if (typeof value.id !== "string")
+        throw new Error(`${where}.id must be a string.`);
+    const verification = value.verification;
+    if (!verification || !Array.isArray(verification.commands)) {
+        throw new Error(`${where}.verification.commands must be an array.`);
+    }
+    const stopCriteria = value.stopCriteria;
+    if (!stopCriteria || typeof stopCriteria.timeoutMinutes !== "number") {
+        throw new Error(`${where}.stopCriteria.timeoutMinutes must be a number.`);
+    }
+    const permissions = value.permissions;
+    if (!permissions || !Array.isArray(permissions.forbiddenPaths)) {
+        throw new Error(`${where}.permissions.forbiddenPaths must be an array.`);
+    }
+}

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

@@ -0,0 +1,83 @@
+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
+        .map((result) => {
+        const status = result.timedOut ? "TIMED OUT" : result.exitCode === 0 ? "pass (exit 0)" : `fail (exit ${result.exitCode})`;
+        const out = [result.stdoutExcerpt, result.stderrExcerpt].filter(Boolean).join("\n");
+        return `#### \`${result.command}\` — ${status} (${result.durationMs} ms)
+
+\`\`\`
+${out || "(no output)"}
+\`\`\``;
+    })
+        .join("\n\n");
+    const forbiddenSection = entry.forbidden.ok
+        ? "No forbidden paths were changed."
+        : entry.forbidden.violations.map((violation) => `- \`${violation.file}\` matched forbidden pattern \`${violation.pattern}\``).join("\n");
+    return `# Proof report — ${loop.title} ${banner}
+
+Loop: \`${entry.loopId}\` · Mode: ${entry.mode} · Iterations: ${entry.iterations}
+Generated: ${entry.timestamp}
+By: ${entry.actor.user ?? "unknown"}@${entry.actor.host ?? "unknown"}
+Audit entry: \`${entry.hash}\`
+
+## Goal
+
+${loop.goal}
+
+## Git
+
+- Base: \`${entry.git.base}\`
+- Before: \`${entry.git.shaBefore ?? "(no commits)"}\`
+- After: \`${entry.git.shaAfter ?? "(no commits)"}\`
+- Working tree clean at start: ${entry.git.clean ? "yes" : "no"}
+
+## Files changed (${changed.length})
+
+${changed.length ? changed.map((file) => `- \`${file}\``).join("\n") : "- (none)"}
+
+\`\`\`
+${entry.changedFiles.diffstat || "(no diffstat)"}
+\`\`\`
+
+## Verification — ${verification.passed ? "passed" : "failed"}
+
+${commandBlocks || "_No verification commands were configured for this loop._"}
+${verification.warnings.length ? `\n> Warnings:\n${verification.warnings.map((warning) => `> - ${warning}`).join("\n")}\n` : ""}
+## Forbidden paths — ${entry.forbidden.ok ? "clean" : "VIOLATION"}
+
+${forbiddenSection}
+${entry.driven && iterationLogs ? `\n${renderIterationHistory(iterationLogs)}` : ""}
+---
+
+${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

@@ -0,0 +1,184 @@
+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 (!(await git.isGitRepo(projectRoot))) {
+        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);
+    const changed = await git.changedFiles(projectRoot, base);
+    const diffstat = await git.diffStat(projectRoot, base);
+    const shaAfter = await git.headSha(projectRoot, "HEAD");
+    const allChanged = [...changed.tracked, ...changed.untracked];
+    const forbidden = checkForbiddenPaths(allChanged, loop.permissions.forbiddenPaths);
+    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 = 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(),
+        project: loopFile.project,
+        loopId: loop.id,
+        mode,
+        actor: { user: safe(() => os.userInfo().username), host: safe(() => os.hostname()) },
+        git: gitInfo,
+        changedFiles: { tracked: changed.tracked, untracked: changed.untracked, diffstat },
+        forbidden: { ok: forbidden.ok, violations: forbidden.violations },
+        verification: {
+            passed: verification.passed,
+            commands: verification.results.map((result) => ({
+                command: result.command,
+                exitCode: result.exitCode,
+                timedOut: result.timedOut,
+                durationMs: result.durationMs
+            }))
+        },
+        iterations,
+        passed
+    };
+}
+async function finalize(projectRoot, loop, input, verification, forbidden, options, iterationLogs) {
+    let entry;
+    if (options.dryRun) {
+        const existing = await readAuditLog(projectRoot);
+        const prevHash = existing.length ? existing[existing.length - 1].hash : null;
+        entry = { ...input, prevHash, hash: hashEntry(input, prevHash) };
+    }
+    else {
+        entry = await appendAuditEntry(projectRoot, input);
+    }
+    let reportPath;
+    if (!options.dryRun && options.writeReport !== false) {
+        const stamp = entry.timestamp.replace(/[:.]/g, "-");
+        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, iterationLogs), "utf8");
+    }
+    if (!options.dryRun) {
+        await appendStateEntry(projectRoot, loop, entry);
+    }
+    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"} — ${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.")) {
+        next = existing.replace("- No attempts yet.", line);
+    }
+    else if (existing) {
+        next = `${existing.trimEnd()}\n${line}\n`;
+    }
+    else {
+        next = `# ${loop.title} state\n\nLoop id: ${loop.id}\n\n## Attempts\n\n${line}\n`;
+    }
+    await fs.mkdir(path.dirname(absolute), { recursive: true });
+    await fs.writeFile(absolute, next, "utf8");
+}
+function safe(getter) {
+    try {
+        return getter();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/verify.js

@@ -0,0 +1,77 @@
+import { spawn } from "node:child_process";
+const EXCERPT_CAP = 64 * 1024;
+const KILL_GRACE_MS = 2000;
+export async function runVerification(commands, options) {
+    const results = [];
+    const warnings = [];
+    const allow = options.allowedCommands?.length ? options.allowedCommands : undefined;
+    for (const command of commands) {
+        if (allow && !allow.includes(command)) {
+            warnings.push(`Verification command is not in the loop's allowed commands: ${command}`);
+        }
+        results.push(await runOne(command, options));
+    }
+    const passed = results.length > 0 && results.every((result) => result.exitCode === 0 && !result.timedOut);
+    return { passed, results, warnings };
+}
+function runOne(command, options) {
+    return new Promise((resolve) => {
+        const start = Date.now();
+        // detached on POSIX so the shell and its children share a process group we can kill together —
+        // otherwise killing the shell leaves grandchildren holding the stdio pipes open and `close` never fires.
+        const posix = process.platform !== "win32";
+        const child = spawn(command, { cwd: options.cwd, shell: true, detached: posix });
+        const killTree = (signal) => {
+            if (child.pid == null)
+                return;
+            try {
+                if (posix)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch {
+                // process group already gone
+            }
+        };
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const capture = (buffer, target) => {
+            const text = buffer.toString("utf8");
+            if (target === "out")
+                stdout = capExcerpt(stdout + text);
+            else
+                stderr = capExcerpt(stderr + text);
+        };
+        child.stdout?.on("data", (buffer) => capture(buffer, "out"));
+        child.stderr?.on("data", (buffer) => capture(buffer, "err"));
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree("SIGTERM");
+            setTimeout(() => killTree("SIGKILL"), KILL_GRACE_MS).unref();
+        }, options.timeoutMs);
+        const finish = (exitCode, signal) => {
+            clearTimeout(timer);
+            resolve({
+                command,
+                exitCode: timedOut ? null : exitCode,
+                signal: signal ?? null,
+                timedOut,
+                durationMs: Date.now() - start,
+                stdoutExcerpt: stdout.trimEnd(),
+                stderrExcerpt: stderr.trimEnd()
+            });
+        };
+        child.on("error", (error) => {
+            stderr = capExcerpt(stderr + `\n[spawn error] ${error instanceof Error ? error.message : String(error)}`);
+            finish(127, null);
+        });
+        child.on("close", (code, signal) => finish(code, signal));
+    });
+}
+function capExcerpt(value) {
+    if (value.length <= EXCERPT_CAP)
+        return value;
+    return value.slice(value.length - EXCERPT_CAP);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopgen",
-  "version": "0.2.1",
+  "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": {