loopgen 0.2.0 → 0.3.0

package/README.md

@@ -139,10 +139,29 @@ 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`)。
+- 说明:v1 是**事后检测,而非沙箱阻断**——它证明改动通过了你的真实验证、且没有改动禁止路径。
+
 可用 adapter：
 
 - `agents-md`：通用 `AGENTS.md`，可被 Claude Code、Codex、Cursor、Copilot、Gemini CLI、Aider 等读取
@@ -350,10 +369,31 @@ 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: 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.
+
 Available adapters:
 
 - `agents-md` — one `AGENTS.md` read by Claude Code, Codex, Cursor, Copilot, Gemini CLI, Aider, and more

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import process from "node:process";
 import readline from "node:readline/promises";
@@ -11,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",
@@ -25,11 +27,13 @@ const PROJECT_MANIFESTS = [
 function looksLikeProject(dir) {
     return PROJECT_MANIFESTS.some((file) => existsSync(path.join(dir, file)));
 }
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
 const program = new Command();
 program
     .name("loopgen")
     .description("Generate bounded, verifiable AI agent configs for Codex, Claude, Cursor, and local models — with safety rails baked in.")
-    .version("0.1.0");
+    .version(version);
 program
     .command("init")
     .argument("[project]", "project directory", ".")
@@ -142,6 +146,35 @@ 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")
+    .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
+    });
+    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;
@@ -193,6 +226,25 @@ 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" : ""})`);
+    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/audit.js

@@ -0,0 +1,52 @@
+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.
+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)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalize(value[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,58 @@
+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;
+}
+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/report.js

@@ -0,0 +1,58 @@
+export function renderProofReport(loop, entry, verification) {
+    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}
+
+---
+
+> 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,108 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+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 { 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.");
+    }
+    const loopFile = await loadLoopFile(projectRoot, options.loopsFile);
+    const loop = selectLoop(loopFile, options.loopId);
+    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 = Math.max(loop.stopCriteria.timeoutMinutes || 1, 1) * 60_000;
+    const verification = await runVerification(loop.verification.commands, {
+        cwd: projectRoot,
+        timeoutMs,
+        allowedCommands: loop.permissions.allowedCommands
+    });
+    const passed = verification.passed && forbidden.ok;
+    const input = {
+        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: { base, shaBefore, shaAfter, clean },
+        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: 1,
+        passed
+    };
+    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), "utf8");
+    }
+    if (!options.dryRun) {
+        await appendStateEntry(projectRoot, loop, entry);
+    }
+    return { loop, passed, entry, verification, forbidden, reportPath, dryRun: Boolean(options.dryRun) };
+}
+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 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.0",
+  "version": "0.3.0",
   "description": "Generate bounded, verifiable AI agent configs for Codex, Claude, Cursor, and local models — with safety rails baked in.",
   "type": "module",
   "engines": {