@tea-agent/loop-agent 0.1.0

package/dist/workflows/loop/actions.js

@@ -0,0 +1,1334 @@
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_CURSOR_MODEL, DEFAULT_CURSOR_TIMEOUT_MS, executeCursorTask, } from "../../executors/cursor-executor.js";
+import { executeShellCommand, } from "../../executors/shell-executor.js";
+import { pathsChangedDuringRun, readGitStatusPorcelain, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "../../executors/shell-write-guard.js";
+import { executeSingleSdkAttempt } from "../../executors/pi-sdk-executor.js";
+import { DEFAULT_PI_MODEL, DEFAULT_PI_PROVIDER } from "../../commands/pi-prompt.js";
+import { runDagReport } from "../../commands/dag-report.js";
+import { runDagRunTask } from "../../commands/dag-run-task.js";
+import { runDagValidate } from "../../commands/dag-validate.js";
+import { runRunDag } from "../../commands/run-dag.js";
+import { compileWorkflowToDag, defaultCompileManifestPath, } from "../dynamic/compile.js";
+import { buildWorkflowSpecForProfile, } from "../dynamic/profiles.js";
+import { parseWorkflowSpec } from "../dynamic/validate.js";
+import { workflowReportSchema } from "../dynamic/artifacts.js";
+import { resumeDagRun, runDag } from "../dag/runner.js";
+import { assertValidDagSpec } from "../dag/validate.js";
+import { assertDagRunTransferTargetAvailable, getDagRunDir, locateDagRun, readHumanEscalation, requirePausedDagRun, transferDagRunDir, writeDagRunState, writeHumanApprovalArtifact, } from "../dag/lifecycle.js";
+import { computeRunDir, persistCursorRunLog } from "../../records/one-shot-runs.js";
+import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
+import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { repoRelativePath, toPosixPath } from "../../shared/path-refs.js";
+import { getLoopPaths } from "./paths.js";
+import { appendLoopRound, readLoopRounds } from "./rounds.js";
+import { rewriteLoopContext } from "./context.js";
+import { loadLoopState } from "./state.js";
+import { drainLoopSignals, pendingLoopSignals, readLoopSignals, } from "./signals.js";
+import { appendLoopEvent } from "./events.js";
+const SUMMARY_LIMIT = 1200;
+const PI_REVIEW_TOOLS = ["read", "grep", "find", "ls"];
+function truncateSummary(text) {
+    const normalized = text.trim();
+    if (normalized.length <= SUMMARY_LIMIT)
+        return normalized;
+    return `${normalized.slice(0, SUMMARY_LIMIT)}\n[truncated]`;
+}
+function extractCommandsFromObjective(objective) {
+    const lines = objective.split("\n");
+    const commands = [];
+    let inVerification = false;
+    for (const line of lines) {
+        if (/^##\s+/.test(line)) {
+            inVerification = /verification|验证/i.test(line);
+            continue;
+        }
+        if (!inVerification)
+            continue;
+        const backtick = line.match(/`([^`]+)`/);
+        if (backtick?.[1]) {
+            commands.push(backtick[1]);
+            continue;
+        }
+        const bullet = line.match(/^[-*]\s+(.+)$/);
+        if (bullet?.[1] && !bullet[1].includes(":")) {
+            commands.push(bullet[1].trim());
+        }
+    }
+    return commands;
+}
+export async function resolveLoopShellVerifyCommands(repoRoot, taskId, explicitCommands = []) {
+    const commands = explicitCommands
+        .map((command) => command.trim())
+        .filter(Boolean);
+    if (commands.length > 0)
+        return commands;
+    const objective = await readFile(getLoopPaths(repoRoot, taskId).objectivePath, "utf-8");
+    const objectiveCommands = extractCommandsFromObjective(objective);
+    if (objectiveCommands.length > 0)
+        return objectiveCommands;
+    const constraints = await readFile(path.join(getTaskPaths(repoRoot, taskId).sourceDir, "执行约束.md"), "utf-8").catch(() => "");
+    const constraintCommands = extractCommandsFromObjective(constraints);
+    if (constraintCommands.length > 0)
+        return constraintCommands;
+    throw new Error("loop shell-verify requires at least one --command or verification commands in objective.md");
+}
+export async function runLoopShellVerification(repoRoot, taskId, options = {}) {
+    const commands = await resolveLoopShellVerifyCommands(repoRoot, taskId, options.commands);
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    const round = rounds.length + 1;
+    const cwd = options.cwd ? path.resolve(repoRoot, options.cwd) : repoRoot;
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const results = [];
+    for (const command of commands) {
+        results.push(await executeShellCommand({ command, cwd, timeoutMs }));
+    }
+    const ok = results.every((result) => result.ok);
+    const paths = getLoopPaths(repoRoot, taskId);
+    await mkdir(paths.verificationDir, { recursive: true });
+    const verificationPath = path.join(paths.verificationDir, `round-${round}.json`);
+    const record = {
+        schemaVersion: 1,
+        taskId,
+        round,
+        action: "shell-verify",
+        ok,
+        commandCount: commands.length,
+        results: results.map((result) => ({
+            command: result.command,
+            cwd: repoRelativePath(repoRoot, result.cwd),
+            durationMs: result.durationMs,
+            exitCode: result.exitCode,
+            failureCategory: result.failureCategory,
+            ok: result.ok,
+            timedOut: result.timedOut,
+            stdoutSummary: truncateSummary(result.stdout),
+            stderrSummary: truncateSummary(result.stderr),
+        })),
+        recordedAt: new Date().toISOString(),
+    };
+    await writeFile(verificationPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+    const failed = results.find((result) => !result.ok);
+    const verification = ok
+        ? `passed: ${commands.join(" && ")}`
+        : `failed: ${failed?.command ?? commands[0]} (${failed?.failureCategory ?? "unknown"})`;
+    await appendLoopRound(repoRoot, taskId, {
+        action: "shell-verify",
+        refs: [repoRelativePath(repoRoot, verificationPath)],
+        result: ok ? "verification passed" : "verification failed",
+        verification,
+        lesson: ok
+            ? "deterministic shell verification passed"
+            : "deterministic shell verification failed; inspect verification ref before another implementation round",
+        next: ok
+            ? "evaluate success criteria coverage"
+            : "fix the failing verification command",
+        decision: ok ? "continue" : "continue",
+        failureCategory: ok ? undefined : failed?.failureCategory,
+        completedCriteria: ok ? ["shell verification action executed"] : [],
+    });
+    await rewriteLoopContext(repoRoot, taskId);
+    return record;
+}
+function latestVerificationSummary(rounds) {
+    const latest = [...rounds].reverse().find((round) => round.verification.trim());
+    return latest
+        ? `${latest.verification}\nrefs=${latest.refs.join(", ")}`
+        : "No verification summary recorded yet.";
+}
+export async function buildLoopPiReviewPrompt(repoRoot, taskId) {
+    const paths = getLoopPaths(repoRoot, taskId);
+    const [objective, context, rounds] = await Promise.all([
+        readFile(paths.objectivePath, "utf-8"),
+        readFile(paths.contextPath, "utf-8"),
+        readLoopRounds(repoRoot, taskId),
+    ]);
+    return [
+        "You are running as a read-only loop-agent loop Pi review action.",
+        "Do not edit files. Do not run shell commands. Use only read, grep, find, and ls tools if tools are needed.",
+        "Review the current loop state and return exactly one JSON object with these fields:",
+        '{"findingSummary":"","failureCategory":"","nextHypothesis":"","recommendedAction":"implement_fix|replan|pause|done","fixScope":["path/or/component"],"rootCause":"","invariant":""}',
+        "recommendedAction must be exactly one of: implement_fix, replan, pause, done.",
+        "",
+        "<objective>",
+        objective.trim(),
+        "</objective>",
+        "",
+        "<context>",
+        context.trim(),
+        "</context>",
+        "",
+        "<latest_verification>",
+        latestVerificationSummary(rounds),
+        "</latest_verification>",
+    ].join("\n");
+}
+function parsePiReviewStructuredOutput(text) {
+    const trimmed = text.trim();
+    const jsonMatch = trimmed.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+        throw new Error("pi-review output did not contain a JSON object");
+    }
+    const parsed = JSON.parse(jsonMatch[0]);
+    for (const key of [
+        "findingSummary",
+        "failureCategory",
+        "nextHypothesis",
+        "recommendedAction",
+        "rootCause",
+    ]) {
+        if (typeof parsed[key] !== "string" || parsed[key].trim().length === 0) {
+            throw new Error(`pi-review output missing structured field: ${key}`);
+        }
+    }
+    if (!Array.isArray(parsed.fixScope) || parsed.fixScope.length === 0) {
+        throw new Error("pi-review output missing structured field: fixScope");
+    }
+    const findingSummary = parsed.findingSummary;
+    const failureCategory = parsed.failureCategory;
+    const nextHypothesis = parsed.nextHypothesis;
+    const recommendedAction = parsed.recommendedAction;
+    const rootCause = parsed.rootCause;
+    if (typeof findingSummary !== "string" ||
+        typeof failureCategory !== "string" ||
+        typeof nextHypothesis !== "string" ||
+        typeof recommendedAction !== "string" ||
+        typeof rootCause !== "string") {
+        throw new Error("pi-review output failed structured field validation");
+    }
+    if (!isLoopPiReviewRecommendedAction(recommendedAction)) {
+        throw new Error(`pi-review output recommendedAction must be one of implement_fix|replan|pause|done, got: ${recommendedAction}`);
+    }
+    const fixScope = parsed.fixScope
+        .filter((value) => typeof value === "string")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (fixScope.length === 0) {
+        throw new Error("pi-review output fixScope must contain at least one non-empty string");
+    }
+    return {
+        findingSummary: findingSummary.trim(),
+        failureCategory: failureCategory.trim(),
+        nextHypothesis: nextHypothesis.trim(),
+        recommendedAction,
+        fixScope,
+        rootCause: rootCause.trim(),
+        invariant: typeof parsed.invariant === "string" ? parsed.invariant.trim() : undefined,
+    };
+}
+function isLoopPiReviewRecommendedAction(value) {
+    return (value === "implement_fix" ||
+        value === "replan" ||
+        value === "pause" ||
+        value === "done");
+}
+async function defaultPiReviewExecutor(input) {
+    const startedAt = Date.now();
+    const result = await executeSingleSdkAttempt({
+        repoRoot: input.cwd,
+        prompt: "You are a read-only reviewer for loop-agent loop. Return only structured JSON.",
+        userMessage: input.prompt,
+        attachedFiles: [],
+        toolNames: [...input.toolNames],
+        timeoutMs: input.timeoutMs,
+        step: "analyze",
+        modelConfig: {
+            provider: input.provider,
+            model: input.model,
+        },
+    });
+    return {
+        ok: result.ok,
+        assistantText: result.assistantText,
+        durationMs: Date.now() - startedAt,
+        failureCategory: result.failureCategory,
+        stderr: result.stderr,
+    };
+}
+async function moveDir(fromDir, toDir) {
+    await mkdir(path.dirname(toDir), { recursive: true });
+    await rename(fromDir, toDir);
+}
+export async function runLoopPiReview(repoRoot, taskId, options = {}) {
+    const provider = options.provider ?? DEFAULT_PI_PROVIDER;
+    const model = options.model ?? DEFAULT_PI_MODEL;
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const cwd = options.cwd ? path.resolve(repoRoot, options.cwd) : repoRoot;
+    const executor = options.executor ?? defaultPiReviewExecutor;
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    const round = rounds.length + 1;
+    const paths = getLoopPaths(repoRoot, taskId);
+    await mkdir(paths.reviewDir, { recursive: true });
+    const prompt = await buildLoopPiReviewPrompt(repoRoot, taskId);
+    const promptPath = path.join(paths.reviewDir, `round-${round}-prompt.md`);
+    await writeFile(promptPath, prompt, "utf-8");
+    const result = await executor({
+        prompt,
+        cwd,
+        provider,
+        model,
+        timeoutMs,
+        toolNames: PI_REVIEW_TOOLS,
+    });
+    let structured;
+    let ok = result.ok;
+    let failureCategory = result.failureCategory ?? "";
+    try {
+        structured = parsePiReviewStructuredOutput(result.assistantText);
+    }
+    catch (error) {
+        ok = false;
+        failureCategory = "invalid-structured-output";
+        structured = {
+            findingSummary: error instanceof Error ? error.message : "pi-review output parse failed",
+            failureCategory,
+            nextHypothesis: "rerun pi-review with a stricter structured-output prompt",
+            recommendedAction: "pause",
+            fixScope: ["unknown"],
+            rootCause: "invalid pi-review structured output",
+            invariant: "do not write until review output is valid",
+        };
+    }
+    const harnessRunsDir = path.join(repoRoot, ".harness", "runs");
+    const activeDir = path.join(harnessRunsDir, "active");
+    const targetLifecycle = ok ? "completed" : "failed";
+    const runId = `${new Date().toISOString().slice(0, 10)}-${taskId}-pi-review-r${round}`;
+    const activeRunDir = path.join(activeDir, runId);
+    await mkdir(activeRunDir, { recursive: true });
+    const runMarkdown = [
+        "# Pi Review Run",
+        "",
+        "| Field | Value |",
+        "|---|---|",
+        `| taskId | ${taskId} |`,
+        `| status | ${ok ? "completed" : "failed"} |`,
+        `| provider | ${provider} |`,
+        `| model | ${model} |`,
+        `| tools | ${PI_REVIEW_TOOLS.join(",")} |`,
+        `| prompt | ${repoRelativePath(repoRoot, promptPath)} |`,
+        "",
+        "## Structured Output",
+        "",
+        "```json",
+        JSON.stringify(structured, null, 2),
+        "```",
+        "",
+        "## Assistant Text Summary",
+        "",
+        truncateSummary(result.assistantText || result.stderr || ""),
+        "",
+    ].join("\n");
+    await writeFile(path.join(activeRunDir, "run.md"), runMarkdown, "utf-8");
+    await writeFile(path.join(activeRunDir, "meta.json"), `${JSON.stringify({
+        runId,
+        taskId,
+        status: ok ? "completed" : "failed",
+        model,
+        provider,
+        channel: "pi-review",
+        cwd,
+        durationMs: result.durationMs,
+        failureCategory,
+        toolNames: PI_REVIEW_TOOLS,
+        logPath: "run.md",
+    }, null, 2)}\n`, "utf-8");
+    const targetRunDir = path.join(harnessRunsDir, targetLifecycle, runId);
+    await moveDir(activeRunDir, targetRunDir);
+    const runRef = repoRelativePath(repoRoot, path.join(targetRunDir, "run.md"));
+    const record = {
+        schemaVersion: 1,
+        taskId,
+        round,
+        action: "pi-review",
+        ok,
+        provider,
+        model,
+        toolNames: PI_REVIEW_TOOLS,
+        promptPath: repoRelativePath(repoRoot, promptPath),
+        runRef,
+        structured,
+        assistantTextSummary: truncateSummary(result.assistantText || result.stderr || ""),
+        failureCategory,
+        recordedAt: new Date().toISOString(),
+    };
+    await writeFile(path.join(paths.reviewDir, `round-${round}.json`), `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+    await appendLoopRound(repoRoot, taskId, {
+        action: "pi-review",
+        refs: [runRef, repoRelativePath(repoRoot, path.join(paths.reviewDir, `round-${round}.json`))],
+        result: ok ? "pi review completed" : "pi review failed",
+        verification: ok
+            ? `pi-review structured output: ${structured.findingSummary}`
+            : `pi-review failed: ${structured.findingSummary}`,
+        lesson: structured.findingSummary,
+        next: structured.recommendedAction,
+        decision: "continue",
+        failureCategory: structured.failureCategory,
+        completedCriteria: ok ? ["pi read-only review action executed"] : [],
+    });
+    await rewriteLoopContext(repoRoot, taskId);
+    return record;
+}
+function normalizePattern(pattern) {
+    return pattern.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/\*\*$/, "");
+}
+function patternsOverlap(allowed, forbidden) {
+    const a = normalizePattern(allowed);
+    const f = normalizePattern(forbidden);
+    return (a === f ||
+        a.startsWith(`${f}/`) ||
+        f.startsWith(`${a}/`) ||
+        pathMatchesPattern(a, forbidden) ||
+        pathMatchesPattern(f, allowed));
+}
+function hasDagRound(rounds) {
+    return rounds.some((round) => round.action === "dag");
+}
+async function readLatestPiReviewRecord(repoRoot, taskId) {
+    const paths = getLoopPaths(repoRoot, taskId);
+    let entries;
+    try {
+        entries = await readdir(paths.reviewDir);
+    }
+    catch {
+        return undefined;
+    }
+    const roundFiles = entries
+        .map((entry) => {
+        const match = entry.match(/^round-(\d+)\.json$/);
+        return match ? { entry, round: Number.parseInt(match[1], 10) } : undefined;
+    })
+        .filter((entry) => Boolean(entry))
+        .sort((a, b) => b.round - a.round);
+    for (const { entry } of roundFiles) {
+        try {
+            const parsed = JSON.parse(await readFile(path.join(paths.reviewDir, entry), "utf-8"));
+            if (parsed.action === "pi-review" && parsed.structured) {
+                return parsed;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+export function validateLoopCursorFixPolicy(input) {
+    if (input.allowedPaths.length === 0) {
+        throw new Error("loop cursor-fix requires non-empty task allowedPaths");
+    }
+    for (const allowed of input.allowedPaths) {
+        for (const forbidden of input.forbiddenPaths) {
+            if (patternsOverlap(allowed, forbidden)) {
+                throw new Error(`loop cursor-fix allowed/forbidden paths overlap: ${allowed} vs ${forbidden}`);
+            }
+        }
+    }
+    if (input.complexity !== undefined &&
+        input.complexity !== "small" &&
+        !input.hasDagRound &&
+        !input.dagFallbackReason?.trim()) {
+        throw new Error("loop cursor-fix for medium/large tasks requires a prior loop dag round or task dagFallbackReason");
+    }
+}
+function extractChangedPaths(result) {
+    const raw = result.details?.changedPaths;
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.filter((value) => typeof value === "string");
+}
+function filterLoopOwnedChangedPaths(changedPaths, repoRoot, runDir) {
+    if (!runDir)
+        return changedPaths;
+    const runDirRelative = normalizePattern(repoRelativePath(repoRoot, runDir));
+    return changedPaths.filter((changedPath) => {
+        const normalized = normalizePattern(changedPath);
+        return normalized !== runDirRelative && !normalized.startsWith(`${runDirRelative}/`);
+    });
+}
+export async function buildLoopCursorFixPrompt(repoRoot, taskId) {
+    const paths = getLoopPaths(repoRoot, taskId);
+    const [objective, context] = await Promise.all([
+        readFile(paths.objectivePath, "utf-8"),
+        readFile(paths.contextPath, "utf-8"),
+    ]);
+    const config = await loadTaskConfig(repoRoot, taskId);
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    const latestReview = await readLatestPiReviewRecord(repoRoot, taskId);
+    validateLoopCursorFixPolicy({
+        allowedPaths: config.allowedPaths,
+        forbiddenPaths: config.forbiddenPaths,
+        complexity: config.complexity,
+        dagFallbackReason: config.dagFallbackReason ?? "",
+        hasDagRound: hasDagRound(rounds),
+    });
+    return [
+        `Task id: ${taskId}`,
+        "Exact objective: implement the next bounded fix described by the loop context.",
+        "",
+        "Allowed paths:",
+        ...config.allowedPaths.map((entry) => `- ${entry}`),
+        "",
+        "Forbidden paths:",
+        ...(config.forbiddenPaths.length > 0
+            ? config.forbiddenPaths.map((entry) => `- ${entry}`)
+            : ["- none"]),
+        "",
+        "Hard constraints:",
+        "- Preserve unrelated files and user work.",
+        "- Do not touch forbidden paths.",
+        "- Do not mark the loop complete; shell verification or review must follow.",
+        "",
+        "Expected verification:",
+        "- Run the verification commands listed in the task constraints after the fix, or explain why they were not run.",
+        "",
+        "<latest_pi_review>",
+        latestReview
+            ? [
+                `recommendedAction: ${latestReview.structured.recommendedAction}`,
+                `rootCause: ${latestReview.structured.rootCause}`,
+                `fixScope: ${latestReview.structured.fixScope.join(", ")}`,
+                `invariant: ${latestReview.structured.invariant ?? "unknown"}`,
+            ].join("\n")
+            : "No structured Pi review record found.",
+        "</latest_pi_review>",
+        "",
+        "<objective>",
+        objective.trim(),
+        "</objective>",
+        "",
+        "<context>",
+        context.trim(),
+        "</context>",
+    ].join("\n");
+}
+async function defaultCursorFixExecutor(input) {
+    return executeCursorTask({
+        task: input.prompt,
+        cwd: input.cwd,
+        model: input.model,
+        timeoutMs: input.timeoutMs,
+        runDir: input.runDir,
+    });
+}
+export async function runLoopCursorFix(repoRoot, taskId, options = {}) {
+    const config = await loadTaskConfig(repoRoot, taskId);
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    validateLoopCursorFixPolicy({
+        allowedPaths: config.allowedPaths,
+        forbiddenPaths: config.forbiddenPaths,
+        complexity: config.complexity,
+        dagFallbackReason: config.dagFallbackReason ?? "",
+        hasDagRound: hasDagRound(rounds),
+    });
+    const model = options.model ?? config.cursorModel ?? DEFAULT_CURSOR_MODEL;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CURSOR_TIMEOUT_MS;
+    const cwd = options.cwd ? path.resolve(repoRoot, options.cwd) : repoRoot;
+    const executor = options.executor ?? defaultCursorFixExecutor;
+    const round = rounds.length + 1;
+    const latestReview = await readLatestPiReviewRecord(repoRoot, taskId);
+    const prompt = await buildLoopCursorFixPrompt(repoRoot, taskId);
+    const runDir = (await computeRunDir(repoRoot, `${taskId} cursor-fix r${round}`)) ?? undefined;
+    const beforeStatus = await readGitStatusPorcelain(repoRoot).catch(() => "");
+    const result = await executor({ prompt, cwd, model, timeoutMs, runDir });
+    const explicitChangedPaths = extractChangedPaths(result);
+    let changedPaths = explicitChangedPaths
+        ? filterLoopOwnedChangedPaths(explicitChangedPaths, repoRoot, runDir)
+        : undefined;
+    const guard = explicitChangedPaths
+        ? validateShellWriteGuard({
+            changedPaths: changedPaths ?? [],
+            writePolicy: "exclusive",
+            writeSet: config.allowedPaths,
+            forbiddenPaths: config.forbiddenPaths,
+        })
+        : await (async () => {
+            const afterStatus = await readGitStatusPorcelain(repoRoot).catch(() => "");
+            changedPaths = filterLoopOwnedChangedPaths(pathsChangedDuringRun(snapshotGitStatusPorcelain(beforeStatus), snapshotGitStatusPorcelain(afterStatus)), repoRoot, runDir);
+            return validateShellWriteGuard({
+                changedPaths,
+                writePolicy: "exclusive",
+                writeSet: config.allowedPaths,
+                forbiddenPaths: config.forbiddenPaths,
+            });
+        })();
+    const finalResult = guard.ok
+        ? result
+        : {
+            ...result,
+            ok: false,
+            status: "failed",
+            failureCategory: "path-violation",
+            stderr: [
+                result.stderr,
+                `loop cursor-fix path violations: ${guard.violations.join(", ")}`,
+            ]
+                .filter(Boolean)
+                .join("\n"),
+        };
+    const persisted = await persistCursorRunLog(repoRoot, {
+        task: prompt,
+        model,
+        channel: "tool",
+        cwd,
+        result: finalResult,
+        taskId,
+        runDir,
+    });
+    const runRef = persisted?.logPath
+        ? repoRelativePath(repoRoot, persisted.logPath)
+        : "";
+    const paths = getLoopPaths(repoRoot, taskId);
+    await mkdir(paths.reviewDir, { recursive: true });
+    const record = {
+        schemaVersion: 1,
+        taskId,
+        round,
+        action: "cursor-fix",
+        ok: finalResult.ok,
+        model,
+        runRef,
+        allowedPaths: config.allowedPaths,
+        forbiddenPaths: config.forbiddenPaths,
+        changedPaths: changedPaths ?? [],
+        writeGuardViolations: guard.violations,
+        fixScope: latestReview?.structured.fixScope ?? [],
+        rootCause: latestReview?.structured.rootCause ?? "",
+        invariant: latestReview?.structured.invariant ?? "",
+        expectedNextVerification: "loop shell-verify or required task verification commands",
+        recordedAt: new Date().toISOString(),
+    };
+    const recordPath = path.join(paths.reviewDir, `round-${round}-cursor-fix.json`);
+    await writeFile(recordPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+    await appendLoopRound(repoRoot, taskId, {
+        action: "cursor-fix",
+        refs: [runRef, repoRelativePath(repoRoot, recordPath)].filter(Boolean),
+        result: finalResult.ok ? "cursor fix completed" : "cursor fix failed",
+        verification: finalResult.ok
+            ? "cursor-fix completed; shell verification still required"
+            : `cursor-fix failed: ${finalResult.failureCategory}`,
+        lesson: finalResult.ok
+            ? "cursor-fix changed only allowed paths; completion remains gated by verification"
+            : finalResult.stderr || finalResult.stdout || "cursor-fix failed",
+        next: "run shell verification for the cursor fix",
+        decision: "continue",
+        failureCategory: finalResult.ok ? undefined : finalResult.failureCategory,
+        completedCriteria: finalResult.ok ? ["cursor bounded fix action executed"] : [],
+    });
+    await rewriteLoopContext(repoRoot, taskId);
+    return record;
+}
+async function captureJsonOutput(fn) {
+    let captured;
+    const originalLog = console.log;
+    console.log = (message) => {
+        if (typeof message === "string") {
+            captured = JSON.parse(message);
+            return;
+        }
+        captured = message;
+    };
+    try {
+        await fn();
+    }
+    finally {
+        console.log = originalLog;
+    }
+    if (captured === undefined) {
+        throw new Error("DAG command produced no JSON output");
+    }
+    return captured;
+}
+async function defaultDagCommandRunner(repoRoot, command, args) {
+    if (command === "dag-run-task") {
+        return captureJsonOutput(() => runDagRunTask(repoRoot, args));
+    }
+    if (command === "dag-validate") {
+        return captureJsonOutput(() => runDagValidate(repoRoot, args));
+    }
+    if (command === "run-dag") {
+        return captureJsonOutput(() => runRunDag(repoRoot, args));
+    }
+    return captureJsonOutput(() => runDagReport(repoRoot, args));
+}
+function asRecord(value, label) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    throw new Error(`${label} did not return a JSON object`);
+}
+function stringField(value, key, label) {
+    const raw = value[key];
+    if (typeof raw === "string" && raw.length > 0)
+        return raw;
+    throw new Error(`${label} missing string field: ${key}`);
+}
+function optionalStringField(value, key) {
+    const raw = value[key];
+    return typeof raw === "string" ? raw : "";
+}
+function relativeRef(repoRoot, value) {
+    if (!value)
+        return "";
+    return path.isAbsolute(value) ? repoRelativePath(repoRoot, value) : toPosixPath(value);
+}
+function firstReportRun(report) {
+    const root = asRecord(report, "dag report");
+    const runs = root.runs;
+    if (!Array.isArray(runs) || runs.length === 0) {
+        throw new Error("dag report JSON did not contain any runs");
+    }
+    return asRecord(runs[0], "dag report run");
+}
+function loopDecisionForDagRun(run) {
+    const lifecycle = optionalStringField(run, "lifecycle");
+    const status = optionalStringField(run, "status");
+    return lifecycle === "paused" || status === "paused" ? "pause" : "continue";
+}
+function loopResultForDagRun(run) {
+    const lifecycle = optionalStringField(run, "lifecycle");
+    const status = optionalStringField(run, "status");
+    if (lifecycle === "paused" || status === "paused") {
+        return "dag run paused";
+    }
+    if (status === "finished")
+        return "dag run finished";
+    if (status === "partial_failed" || status === "failed") {
+        return `dag run ${status}`;
+    }
+    return `dag run status=${status || "unknown"}`;
+}
+function dagFailureCategory(run) {
+    const raw = optionalStringField(run, "failureCategory");
+    if (raw)
+        return raw;
+    const status = optionalStringField(run, "status");
+    if (status === "partial_failed" || status === "failed")
+        return status;
+    return "";
+}
+export async function runLoopDagAction(repoRoot, taskId, options = {}) {
+    const mode = options.mode ?? "review";
+    const cwd = options.cwd ? path.resolve(repoRoot, options.cwd) : repoRoot;
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    const round = rounds.length + 1;
+    const paths = getLoopPaths(repoRoot, taskId);
+    const dagEvidenceDir = path.join(paths.loopDir, "dag");
+    await mkdir(dagEvidenceDir, { recursive: true });
+    const dagPath = options.dagPath
+        ? path.resolve(repoRoot, options.dagPath)
+        : path.join(dagEvidenceDir, `round-${round}.dag.json`);
+    const runner = options.runner ??
+        ((command, args) => defaultDagCommandRunner(repoRoot, command, args));
+    let generated = {};
+    if (!options.dagPath) {
+        generated = asRecord(await runner("dag-run-task", [
+            taskId,
+            "--profile",
+            "auto",
+            "--strict-models",
+            "--output",
+            dagPath,
+            "--cwd",
+            cwd,
+        ]), "dag run-task");
+    }
+    await runner("dag-validate", [
+        "--dag",
+        dagPath,
+        "--strict-models",
+        "--strict-governance",
+    ]);
+    let runId = "";
+    let runStatus = "not-run";
+    let runLifecycle = "not-run";
+    let runRef = "";
+    let reportRef = "";
+    let failureCategory = "";
+    let decision = "continue";
+    let result = "dag generated and strict-governance validated";
+    let lesson = "DAG review packet is ready; inspect writeSet, gates, and expected verification before execution.";
+    let completedCriteria = ["dag generated and strict-governance validated"];
+    if (mode === "execute") {
+        const runArgs = ["--dag", dagPath, "--cwd", cwd];
+        if (options.runId)
+            runArgs.push("--run-id", options.runId);
+        if (options.maxConcurrent !== undefined) {
+            runArgs.push("--max-concurrent", String(options.maxConcurrent));
+        }
+        if (options.noCursor)
+            runArgs.push("--no-cursor");
+        const runSummary = asRecord(await runner("run-dag", runArgs), "run-dag");
+        runId = stringField(runSummary, "runId", "run-dag");
+        const report = await runner("dag-report", [
+            "--run-id",
+            runId,
+            "--json",
+            "--lifecycle",
+            "all",
+        ]);
+        const run = firstReportRun(report);
+        runStatus = stringField(run, "status", "dag report run");
+        runLifecycle = stringField(run, "lifecycle", "dag report run");
+        runRef = relativeRef(repoRoot, stringField(run, "runDir", "dag report run"));
+        failureCategory = dagFailureCategory(run);
+        decision = loopDecisionForDagRun(run);
+        result = loopResultForDagRun(run);
+        lesson =
+            decision === "pause"
+                ? "DAG run paused for human approval; use DAG decision commands before resuming."
+                : "DAG run facts recorded; inspect dag report and follow with shell verification or review.";
+        completedCriteria = ["dag round action executed"];
+    }
+    const recordPath = path.join(dagEvidenceDir, `round-${round}.json`);
+    reportRef = repoRelativePath(repoRoot, recordPath);
+    const record = {
+        schemaVersion: 1,
+        taskId,
+        round,
+        action: "dag",
+        mode,
+        ok: mode === "review" || runStatus === "finished",
+        dagPath: relativeRef(repoRoot, dagPath),
+        strictValidateOk: true,
+        runId,
+        runStatus,
+        runLifecycle,
+        runRef,
+        reportRef,
+        reviewPacket: generated.reviewPacket,
+        failureCategory,
+        expectedNextVerification: decision === "pause"
+            ? "approve or reject paused DAG run, then resume or replan"
+            : "run shell verification or review DAG report before completion",
+        recordedAt: new Date().toISOString(),
+    };
+    await writeFile(recordPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+    await appendLoopRound(repoRoot, taskId, {
+        action: "dag",
+        refs: [runRef, record.dagPath, reportRef].filter(Boolean),
+        result,
+        verification: mode === "review"
+            ? "dag generated and validated with --strict-models --strict-governance"
+            : `dag report status=${runStatus}, lifecycle=${runLifecycle}`,
+        lesson,
+        next: record.expectedNextVerification,
+        decision,
+        failureCategory,
+        completedCriteria,
+    });
+    await rewriteLoopContext(repoRoot, taskId);
+    return record;
+}
+function summarizeWorkflowReport(raw) {
+    if (!raw?.trim()) {
+        return {
+            markdown: "# Workflow Report\n\nNo final workflow report output was emitted.\n",
+            verification: "workflow produced no final report output",
+            result: "workflow run finished without final report output",
+        };
+    }
+    try {
+        const parsed = workflowReportSchema.parse(JSON.parse(raw));
+        return {
+            markdown: [
+                "# Workflow Report",
+                "",
+                parsed.summary,
+                "",
+                `- Verified findings: ${parsed.verifiedFindings.length}`,
+                `- Uncertain findings: ${parsed.uncertainFindings.length}`,
+                `- Refuted findings ref: ${parsed.refutedFindingsRef ?? "none"}`,
+                "",
+            ].join("\n"),
+            verification: `${parsed.verifiedFindings.length} verified, ${parsed.uncertainFindings.length} uncertain`,
+            result: parsed.summary,
+        };
+    }
+    catch {
+        return {
+            markdown: `# Workflow Report\n\n${raw.trim()}\n`,
+            verification: "workflow final output was not a standard WorkflowReport",
+            result: "workflow run produced a non-standard final report",
+        };
+    }
+}
+function workflowFailureCategory(nodes) {
+    for (const node of Object.values(nodes)) {
+        if (node.status === "ERROR")
+            return node.failureCategory ?? "workflow-node-error";
+    }
+    return "";
+}
+export async function runLoopWorkflowAction(repoRoot, taskId, options = {}) {
+    const mode = options.mode ?? "review";
+    const cwd = options.cwd ? path.resolve(repoRoot, options.cwd) : repoRoot;
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    const round = rounds.length + 1;
+    const taskPaths = getTaskPaths(repoRoot, taskId);
+    const workflowRoot = path.join(taskPaths.taskDir, "workflows");
+    const plannedDir = path.join(workflowRoot, "planned");
+    const compiledDir = path.join(workflowRoot, "compiled");
+    const reportsDir = path.join(workflowRoot, "reports");
+    await mkdir(plannedDir, { recursive: true });
+    await mkdir(compiledDir, { recursive: true });
+    await mkdir(reportsDir, { recursive: true });
+    const profile = options.profile ?? "pr-review";
+    const workflowPath = options.workflowPath
+        ? path.resolve(repoRoot, options.workflowPath)
+        : path.join(plannedDir, `${profile}.workflow.json`);
+    const workflow = options.workflowPath
+        ? parseWorkflowSpec(JSON.parse(await readFile(workflowPath, "utf-8")))
+        : buildWorkflowSpecForProfile({
+            profile,
+            taskId,
+            base: options.base,
+            head: options.head,
+            changedFiles: options.changedFiles,
+        });
+    if (!options.workflowPath) {
+        await writeFile(workflowPath, `${JSON.stringify(workflow, null, 2)}\n`, "utf-8");
+    }
+    const compiledDagPath = path.join(compiledDir, `${workflow.meta.name}.dag.json`);
+    const compileManifestPath = defaultCompileManifestPath(compiledDagPath);
+    const compiled = compileWorkflowToDag(workflow, { sourcePath: workflowPath });
+    assertValidDagSpec(compiled.dag, { strictGovernance: true });
+    await writeFile(compiledDagPath, `${JSON.stringify(compiled.dag, null, 2)}\n`, "utf-8");
+    await writeFile(compileManifestPath, `${JSON.stringify(compiled.manifest, null, 2)}\n`, "utf-8");
+    let runId = "";
+    let runStatus = "not-run";
+    let runRef = "";
+    let failureCategory = "";
+    let decision = "continue";
+    let result = "workflow planned, compiled, and strict-governance validated";
+    let verification = "workflow compiled DAG validated with strict governance";
+    let expectedNextVerification = "inspect workflow DAG/report refs before executing or closing out";
+    const reportPath = path.join(reportsDir, `${workflow.meta.name}.workflow-report.md`);
+    if (mode === "execute") {
+        const summary = await runDag(compiled.dag, {
+            cwd,
+            runId: options.runId,
+            maxConcurrent: options.maxConcurrent,
+        });
+        runId = summary.runId;
+        runStatus = summary.status;
+        runRef = relativeRef(repoRoot, summary.runDir);
+        failureCategory = workflowFailureCategory(summary.nodes);
+        decision = runStatus === "paused" ? "pause" : "continue";
+        expectedNextVerification =
+            decision === "pause"
+                ? "approve or reject paused workflow DAG run, then resume or replan"
+                : "review workflow report and run any required shell verification";
+        const report = summarizeWorkflowReport(summary.nodes[workflow.final.from]?.stdout);
+        result = report.result;
+        verification = `workflow run status=${runStatus}; ${report.verification}`;
+        await writeFile(reportPath, report.markdown, "utf-8");
+    }
+    else {
+        await writeFile(reportPath, "# Workflow Report\n\nWorkflow was compiled in review mode and not executed.\n", "utf-8");
+    }
+    const record = {
+        schemaVersion: 1,
+        taskId,
+        round,
+        action: "workflow",
+        mode,
+        profile: workflow.meta.name,
+        ok: mode === "review" || runStatus === "finished",
+        workflowRef: relativeRef(repoRoot, workflowPath),
+        compiledDagRef: relativeRef(repoRoot, compiledDagPath),
+        compileManifestRef: relativeRef(repoRoot, compileManifestPath),
+        runId,
+        runStatus,
+        runRef,
+        reportRef: relativeRef(repoRoot, reportPath),
+        result,
+        verification,
+        failureCategory,
+        expectedNextVerification,
+        recordedAt: new Date().toISOString(),
+    };
+    await appendLoopRound(repoRoot, taskId, {
+        action: "workflow",
+        refs: [
+            record.workflowRef,
+            record.compiledDagRef,
+            record.compileManifestRef,
+            record.runRef,
+            record.reportRef,
+        ].filter(Boolean),
+        result,
+        verification,
+        lesson: mode === "review"
+            ? "Workflow spec is planned and compiled; inspect workflow refs before execution."
+            : "Workflow run facts recorded by ref; keep detailed node outputs in DAG artifacts.",
+        next: expectedNextVerification,
+        decision,
+        failureCategory,
+        completedCriteria: ["workflow round action executed"],
+    });
+    await rewriteLoopContext(repoRoot, taskId);
+    return record;
+}
+function dagRunIdFromRef(ref) {
+    const normalized = ref.split(path.sep).join("/");
+    const match = normalized.match(/\.harness\/dag-runs\/paused\/([^/]+)/);
+    return match?.[1];
+}
+function dagRunIdFromApprovalMessage(message) {
+    const match = message.match(/\brun[-_ ]?id\s*[:=]\s*([a-zA-Z0-9][a-zA-Z0-9_-]*)/i);
+    return match?.[1];
+}
+async function findPausedWorkflowGateRunId(input) {
+    const candidates = new Set();
+    const fromMessage = dagRunIdFromApprovalMessage(input.signal.message);
+    if (fromMessage)
+        candidates.add(fromMessage);
+    for (const ref of input.signal.refs) {
+        const fromRef = dagRunIdFromRef(ref);
+        if (fromRef)
+            candidates.add(fromRef);
+    }
+    const rounds = await readLoopRounds(input.repoRoot, input.taskId);
+    for (const round of [...rounds].reverse()) {
+        if (round.action !== "workflow")
+            continue;
+        for (const ref of round.refs) {
+            const fromRef = dagRunIdFromRef(ref);
+            if (fromRef)
+                candidates.add(fromRef);
+        }
+    }
+    for (const candidate of candidates) {
+        const located = await locateDagRun(input.repoRoot, candidate);
+        if (located?.lifecycle === "paused")
+            return candidate;
+    }
+    return undefined;
+}
+async function approvePausedDagRunFromSignal(input) {
+    const { runDir, state } = await requirePausedDagRun(input.repoRoot, input.runId);
+    const nodeId = state.pausedByNodeId;
+    const node = state.nodes[nodeId];
+    if (!node) {
+        throw new Error(`paused node ${nodeId} not found in run state`);
+    }
+    const escalation = await readHumanEscalation(runDir, nodeId);
+    const options = escalation.humanEscalation.options.map((entry) => entry.id);
+    const selectedOption = escalation.humanEscalation.recommendedOption &&
+        options.includes(escalation.humanEscalation.recommendedOption)
+        ? escalation.humanEscalation.recommendedOption
+        : options[0];
+    if (!selectedOption) {
+        throw new Error(`missing human escalation options for node ${nodeId}`);
+    }
+    const activeRunDir = getDagRunDir(input.repoRoot, "active", state.runId);
+    await assertDagRunTransferTargetAvailable(activeRunDir);
+    const approvedAt = new Date().toISOString();
+    const artifact = {
+        schemaVersion: 1,
+        runId: state.runId,
+        nodeId,
+        decision: "approved",
+        selectedOption,
+        notes: `Approved by loop approval signal ${input.signal.id}: ${input.signal.message}`,
+        approvedAt,
+        escalationArtifactPath: node.escalationArtifactPath,
+    };
+    const approvalPath = await writeHumanApprovalArtifact({
+        runDir,
+        nodeId,
+        artifact,
+    });
+    node.pauseReason = undefined;
+    node.humanApprovalArtifactPath = approvalPath;
+    state.status = "running";
+    state.humanDecisionNodeId = nodeId;
+    delete state.pausedAt;
+    delete state.pausedByNodeId;
+    delete state.pauseReason;
+    await writeDagRunState(runDir, state);
+    await transferDagRunDir(runDir, activeRunDir);
+    return { selectedOption };
+}
+export async function runLoopWorkflowGateSignalAction(repoRoot, taskId, signals = []) {
+    const approvalSignal = pendingLoopSignals(signals).find((signal) => signal.type === "approval");
+    if (!approvalSignal)
+        return undefined;
+    const runId = await findPausedWorkflowGateRunId({
+        repoRoot,
+        taskId,
+        signal: approvalSignal,
+    });
+    if (!runId)
+        return undefined;
+    const rounds = await readLoopRounds(repoRoot, taskId);
+    const round = rounds.length + 1;
+    const approval = await approvePausedDagRunFromSignal({
+        repoRoot,
+        runId,
+        signal: approvalSignal,
+    });
+    const summary = await resumeDagRun({ cwd: repoRoot, runId });
+    const runRef = relativeRef(repoRoot, summary.runDir);
+    const failureCategory = workflowFailureCategory(summary.nodes);
+    const decision = summary.status === "paused" ? "pause" : "continue";
+    const expectedNextVerification = decision === "pause"
+        ? "approve or reject paused workflow DAG run, then resume or replan"
+        : "review resumed workflow report and run any required shell verification";
+    const result = `approval signal satisfied workflow human gate for DAG run ${runId}`;
+    const verification = `workflow gate approved with option=${approval.selectedOption}; resumed status=${summary.status}`;
+    const record = {
+        schemaVersion: 1,
+        taskId,
+        round,
+        action: "workflow-gate-signal",
+        ok: summary.status === "finished",
+        signalId: approvalSignal.id,
+        runId,
+        selectedOption: approval.selectedOption,
+        runStatus: summary.status,
+        runRef,
+        result,
+        verification,
+        failureCategory,
+        expectedNextVerification,
+        recordedAt: new Date().toISOString(),
+    };
+    await appendLoopRound(repoRoot, taskId, {
+        action: "workflow-gate-signal",
+        refs: [...approvalSignal.refs, runRef].filter(Boolean),
+        result,
+        verification,
+        lesson: "Loop approval signal was converted into the existing DAG approval/resume lifecycle.",
+        next: expectedNextVerification,
+        decision,
+        failureCategory,
+        completedCriteria: ["workflow human gate approval signal consumed"],
+    });
+    await drainLoopSignals(repoRoot, taskId, [approvalSignal.id]);
+    await rewriteLoopContext(repoRoot, taskId);
+    return record;
+}
+export function decideNextLoopAutoAction(state, signals = [], options = {}) {
+    const pendingSignals = pendingLoopSignals(signals);
+    const urgent = pendingSignals.find((signal) => signal.urgent);
+    if (urgent) {
+        return {
+            action: "pause",
+            reason: `urgent ${urgent.type} signal: ${urgent.message}`,
+            decision: "pause",
+        };
+    }
+    const scopeChanged = pendingSignals.find((signal) => signal.type === "scope_changed");
+    if (scopeChanged) {
+        return {
+            action: "pause",
+            reason: `scope changed signal requires objective/context review: ${scopeChanged.message}`,
+            decision: "pause",
+        };
+    }
+    const reviewSignal = pendingSignals.find((signal) => signal.type === "review_feedback" || signal.type === "human_followup");
+    if (reviewSignal) {
+        return {
+            action: "pi-review",
+            reason: `${reviewSignal.type} signal requires read-only review: ${reviewSignal.message}`,
+            decision: "continue",
+        };
+    }
+    if (state.round >= state.maxRounds) {
+        return {
+            action: "blocked",
+            reason: `loop maxRounds reached (${state.round}/${state.maxRounds})`,
+            decision: "blocked",
+        };
+    }
+    if (state.failureStreak.category && state.failureStreak.count >= 2) {
+        return {
+            action: "blocked",
+            reason: `repeated failure category ${state.failureStreak.category} x${state.failureStreak.count}`,
+            decision: "blocked",
+        };
+    }
+    if (state.freshness.sourceStale) {
+        return {
+            action: "pause",
+            reason: "task source changed; rebuild or review action prompt before continuing",
+            decision: "pause",
+        };
+    }
+    if (state.lastAction === "shell-verify") {
+        return {
+            action: "pi-review",
+            reason: "shell verification already ran; request read-only review before next implementation decision",
+            decision: "continue",
+        };
+    }
+    if (state.lastAction === "pi-review") {
+        if (options.latestPiReview?.recommendedAction === "implement_fix") {
+            const policy = options.loopAutoWritePolicy ?? "off";
+            const approvalSignal = pendingSignals.find((signal) => signal.type === "approval");
+            const allowedByPolicy = policy === "enabled" ||
+                (policy === "approval-required" &&
+                    (Boolean(options.allowCursorFix) || Boolean(approvalSignal)));
+            if (options.cursorFixPolicyError) {
+                return {
+                    action: "pause",
+                    reason: `cursor-fix policy guard failed: ${options.cursorFixPolicyError}`,
+                    decision: "pause",
+                };
+            }
+            if (allowedByPolicy) {
+                return {
+                    action: "cursor-fix",
+                    reason: `pi-review recommended implement_fix; loopAutoWritePolicy=${policy}`,
+                    decision: "continue",
+                };
+            }
+        }
+        return {
+            action: "dag",
+            reason: "read-only review produced next action; generate a governed DAG review packet",
+            decision: "continue",
+        };
+    }
+    const approvalSignal = pendingSignals.find((signal) => signal.type === "approval");
+    if (approvalSignal) {
+        return {
+            action: "dag",
+            reason: `approval signal received; generate next governed DAG packet: ${approvalSignal.message}`,
+            decision: "continue",
+        };
+    }
+    if (state.lastAction === "cursor-fix" || state.lastAction === "dag") {
+        return {
+            action: "shell-verify",
+            reason: `${state.lastAction} round must be followed by deterministic shell verification`,
+            decision: "continue",
+        };
+    }
+    return {
+        action: "dag",
+        reason: "default to DAG governed review packet for the next bounded round",
+        decision: "continue",
+    };
+}
+async function defaultAutoActionRunner(input) {
+    if (input.action === "shell-verify") {
+        await runLoopShellVerification(input.repoRoot, input.taskId);
+        return;
+    }
+    if (input.action === "pi-review") {
+        await runLoopPiReview(input.repoRoot, input.taskId);
+        return;
+    }
+    if (input.action === "cursor-fix") {
+        await runLoopCursorFix(input.repoRoot, input.taskId);
+        return;
+    }
+    if (input.action === "dag") {
+        await runLoopDagAction(input.repoRoot, input.taskId);
+        return;
+    }
+    await appendLoopRound(input.repoRoot, input.taskId, {
+        action: `auto-${input.action}`,
+        result: input.reason,
+        verification: "deterministic auto policy decision",
+        lesson: input.reason,
+        next: input.action === "blocked"
+            ? "manual intervention required before auto loop can continue"
+            : "review source changes before continuing",
+        decision: input.decision,
+        failureCategory: input.action === "blocked" ? "auto-policy-blocked" : undefined,
+    });
+    await rewriteLoopContext(input.repoRoot, input.taskId);
+}
+export async function runLoopAuto(repoRoot, taskId, options = {}) {
+    const maxRounds = options.maxRounds ?? 1;
+    if (!Number.isInteger(maxRounds) || maxRounds <= 0) {
+        throw new Error("loop auto --max-rounds must be a positive integer");
+    }
+    const runner = options.runner ?? defaultAutoActionRunner;
+    const actions = [];
+    for (let index = 0; index < maxRounds; index += 1) {
+        const state = await loadLoopState(repoRoot, taskId);
+        const signals = await readLoopSignals(repoRoot, taskId);
+        const taskConfig = await loadTaskConfig(repoRoot, taskId);
+        const latestPiReview = await readLatestPiReviewRecord(repoRoot, taskId);
+        const pendingSignalIds = pendingLoopSignals(signals).map((signal) => signal.id);
+        const workflowGateSignalRecord = await runLoopWorkflowGateSignalAction(repoRoot, taskId, signals);
+        if (workflowGateSignalRecord) {
+            const decision = {
+                action: "workflow",
+                reason: `approval signal satisfied paused workflow gate for run ${workflowGateSignalRecord.runId}`,
+                decision: workflowGateSignalRecord.runStatus === "paused" ? "pause" : "continue",
+            };
+            actions.push(decision);
+            await appendLoopEvent(repoRoot, taskId, {
+                type: "action_start",
+                round: state.round + 1,
+                message: `auto selected ${decision.action}: ${decision.reason}`,
+            });
+            const updated = await loadLoopState(repoRoot, taskId);
+            if (updated.lastDecision !== "continue" || updated.status !== "running") {
+                break;
+            }
+            continue;
+        }
+        const hasApprovalSignal = pendingLoopSignals(signals).some((signal) => signal.type === "approval");
+        const policyAllowsCursorFix = taskConfig.loopAutoWritePolicy === "enabled" ||
+            (taskConfig.loopAutoWritePolicy === "approval-required" &&
+                (Boolean(options.allowCursorFix) || hasApprovalSignal));
+        let cursorFixPolicyError;
+        if (policyAllowsCursorFix &&
+            state.lastAction === "pi-review" &&
+            latestPiReview?.structured.recommendedAction === "implement_fix") {
+            try {
+                const rounds = await readLoopRounds(repoRoot, taskId);
+                validateLoopCursorFixPolicy({
+                    allowedPaths: taskConfig.allowedPaths,
+                    forbiddenPaths: taskConfig.forbiddenPaths,
+                    complexity: taskConfig.complexity,
+                    dagFallbackReason: taskConfig.dagFallbackReason ?? "",
+                    hasDagRound: hasDagRound(rounds),
+                });
+            }
+            catch (error) {
+                cursorFixPolicyError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        const next = decideNextLoopAutoAction(state, signals, {
+            loopAutoWritePolicy: taskConfig.loopAutoWritePolicy,
+            allowCursorFix: options.allowCursorFix,
+            latestPiReview: latestPiReview?.structured,
+            cursorFixPolicyError,
+        });
+        actions.push(next);
+        await appendLoopEvent(repoRoot, taskId, {
+            type: "action_start",
+            round: state.round + 1,
+            message: `auto selected ${next.action}: ${next.reason}`,
+        });
+        await runner({ ...next, repoRoot, taskId });
+        if (pendingSignalIds.length > 0) {
+            await drainLoopSignals(repoRoot, taskId, pendingSignalIds);
+        }
+        const updated = await loadLoopState(repoRoot, taskId);
+        if (updated.lastDecision !== "continue" || updated.status !== "running") {
+            break;
+        }
+    }
+    const finalState = await loadLoopState(repoRoot, taskId);
+    await appendLoopEvent(repoRoot, taskId, {
+        type: "loop_finish",
+        round: finalState.round,
+        message: `auto loop stopped with status ${finalState.status}`,
+    });
+    return {
+        schemaVersion: 1,
+        taskId,
+        actions,
+        roundsRun: actions.length,
+        finalStatus: finalState.status,
+        recordedAt: new Date().toISOString(),
+    };
+}