@tea-agent/loop-agent 0.1.0

package/dist/workflows/dag/runner.js

@@ -0,0 +1,1677 @@
+import { createHash } from "node:crypto";
+import { access, appendFile, cp, mkdir, readdir, readFile, rm, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { CANONICAL_TASK_ID_PATTERN, formatLocalCompactDate, } from "../../task/runtime.js";
+import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, isPauseOnHumanDecisionGate, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
+import { repoRelativePath } from "../../shared/path-refs.js";
+import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, requireActiveDagRun, transferDagRunDir, writeDagRunState, } from "./lifecycle.js";
+import { createDagNodeExecutor } from "./executor-registry.js";
+import { executeDagCursorNode } from "../../executors/dag-cursor-executor.js";
+import { executeDagPiNode } from "../../executors/dag-pi-executor.js";
+import { assertValidDagSpec } from "./validate.js";
+import { normalizeDagPromptSources } from "./prompt-source.js";
+import { buildDagNodePromptEnvelope } from "./prompt.js";
+import { persistLongNodeOutputArtifacts, relocateRunArtifactPaths, } from "./upstream-artifacts.js";
+import { resolveDagSkillInstructions, skillInstructionMetadata, } from "./skill-instructions.js";
+import { resolveDagNodeSkills } from "./skills.js";
+import { topoSortToRanks } from "./topo.js";
+import { parseDagSpec, resolveModelForTask, } from "./types.js";
+import { buildVerifiedFindingsReport, findingSchema, verificationSchema, } from "../dynamic/artifacts.js";
+import { parseRepairArtifactFromText, validateRepairArtifactScope, } from "./repair-artifact.js";
+async function prepareDagRunDir(runDir) {
+    await rm(runDir, { recursive: true, force: true });
+    await mkdir(runDir, { recursive: true });
+}
+async function writeDagRunSpec(runDir, spec) {
+    await writeFile(path.join(runDir, "run.json"), `${JSON.stringify(spec, null, 2)}\n`, "utf-8");
+}
+export async function loadDagSpecFromFile(dagPath) {
+    const raw = JSON.parse(await readFile(dagPath, "utf-8"));
+    const normalized = await normalizeDagPromptSources(raw, path.dirname(dagPath));
+    return parseDagSpec(normalized);
+}
+export const CANONICAL_DAG_RUN_ID_PATTERN = /^\d{8}-[a-z0-9]+(-[a-z0-9]+)*$/;
+const TASK_ID_IN_TEXT_PATTERN = /\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*/g;
+export function toKebabSlug(text, maxLen = 40) {
+    return (text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, maxLen) || "dag");
+}
+export function extractTaskIdFromDagSpec(spec) {
+    if (spec.objective) {
+        const match = spec.objective.match(TASK_ID_IN_TEXT_PATTERN);
+        if (match)
+            return match[0];
+    }
+    for (const line of spec.globalConstraints ?? []) {
+        const match = line.match(TASK_ID_IN_TEXT_PATTERN);
+        if (match)
+            return match[0];
+    }
+    return undefined;
+}
+export function deriveDagRunSlug(spec) {
+    const taskId = extractTaskIdFromDagSpec(spec);
+    if (taskId && CANONICAL_TASK_ID_PATTERN.test(taskId)) {
+        return taskId.slice(11);
+    }
+    return toKebabSlug(spec.title);
+}
+export function validateDagRunIdFormat(runId) {
+    const warnings = [];
+    if (!CANONICAL_DAG_RUN_ID_PATTERN.test(runId)) {
+        warnings.push(`run-id "${runId}" does not match canonical YYYYMMDD-<slug>; legacy run facts remain readable`);
+    }
+    return { warnings };
+}
+async function listExistingDagRunIds(cwd) {
+    const ids = new Set();
+    for (const lifecycle of ["active", "completed", "paused"]) {
+        const dir = path.join(cwd, ".harness", "dag-runs", lifecycle);
+        try {
+            const entries = await readdir(dir);
+            for (const entry of entries) {
+                if (entry !== ".gitkeep")
+                    ids.add(entry);
+            }
+        }
+        catch {
+            // lifecycle dir may not exist in minimal fixtures.
+        }
+    }
+    return ids;
+}
+export function collisionSafeDagRunId(baseId, existing, now = new Date()) {
+    if (!existing.has(baseId))
+        return baseId;
+    for (let round = 2; round <= 99; round += 1) {
+        const candidate = `${baseId}-r${round}`;
+        if (!existing.has(candidate))
+            return candidate;
+    }
+    const hh = String(now.getHours()).padStart(2, "0");
+    const mm = String(now.getMinutes()).padStart(2, "0");
+    const ss = String(now.getSeconds()).padStart(2, "0");
+    const timed = `${baseId}-${hh}${mm}${ss}`;
+    if (!existing.has(timed))
+        return timed;
+    return `${timed}-r2`;
+}
+export async function buildDagRunId(spec, options) {
+    const now = options?.now ?? new Date();
+    const datePrefix = formatLocalCompactDate(now);
+    const baseId = `${datePrefix}-${deriveDagRunSlug(spec)}`;
+    if (!options?.cwd)
+        return baseId;
+    const existing = await listExistingDagRunIds(options.cwd);
+    return collisionSafeDagRunId(baseId, existing, now);
+}
+export function buildNodePrompt(spec, task, upstream) {
+    return buildDagNodePromptEnvelope({
+        spec,
+        task,
+        upstream,
+        resolvedSkills: resolveDagNodeSkills(spec, task),
+    });
+}
+export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd) {
+    const skillNames = resolveDagNodeSkills(spec, task);
+    const resolvedSkillInstructions = task.executor === "cursor" || task.executor === "pi"
+        ? await resolveDagSkillInstructions(skillNames, {
+            cwd,
+            includeLearnedPatterns: task.role === "implementer",
+        })
+        : [];
+    return {
+        prompt: buildDagNodePromptEnvelope({
+            spec,
+            task,
+            upstream,
+            resolvedSkills: skillNames,
+            resolvedSkillInstructions,
+        }),
+        resolvedSkills: skillInstructionMetadata(resolvedSkillInstructions),
+    };
+}
+export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "dag") {
+    const nodes = {};
+    for (const task of spec.tasks) {
+        nodes[task.id] = {
+            id: task.id,
+            status: "PENDING",
+            executor: task.executor,
+            complexity: task.complexity,
+        };
+    }
+    return {
+        version: 1,
+        title: spec.title,
+        runId,
+        cwd: opts.cwd,
+        startedAt: new Date().toISOString(),
+        status: opts.initOnly || opts.dryRun ? "pending" : "running",
+        ranks,
+        nodes,
+        ...(shouldEnableDagConvergence(spec)
+            ? {
+                convergence: {
+                    enabled: true,
+                    maxPasses: Math.max(1, spec.convergence?.maxPasses ?? 3),
+                    currentPass: 1,
+                    passHistory: [],
+                },
+            }
+            : {}),
+    };
+}
+export async function runDag(spec, opts) {
+    assertValidDagSpec(spec);
+    const { ranks } = topoSortToRanks(spec);
+    const maxConcurrent = Math.max(1, opts.maxConcurrent ?? 4);
+    let runId = opts.runId;
+    if (runId) {
+        for (const warning of validateDagRunIdFormat(runId).warnings) {
+            console.warn(`[run-dag] warning: ${warning}`);
+        }
+    }
+    else {
+        runId = await buildDagRunId(spec, { cwd: opts.cwd });
+    }
+    const state = createInitialRunState(spec, opts, ranks, runId);
+    const activeRunDir = getDagRunDir(opts.cwd, "active", state.runId);
+    const completedRunDir = getDagRunDir(opts.cwd, "completed", state.runId);
+    const pausedRunDir = getDagRunDir(opts.cwd, "paused", state.runId);
+    const runDir = activeRunDir;
+    await prepareDagRunDir(runDir);
+    await writeDagRunSpec(runDir, spec);
+    await writeDagRunState(runDir, state);
+    await notifyRunObserver(opts.observer, "onRunStart", state);
+    if (opts.dryRun || opts.initOnly) {
+        return {
+            title: spec.title,
+            runId: state.runId,
+            status: state.status,
+            ranks,
+            nodes: state.nodes,
+            runDir,
+        };
+    }
+    try {
+        return await executeDagCheckpoint({
+            spec,
+            state,
+            ranks,
+            runDir,
+            cwd: opts.cwd,
+            maxConcurrent,
+            executeNode: opts.executeNode,
+            observer: opts.observer,
+            activeRunDir,
+            completedRunDir,
+            pausedRunDir,
+        });
+    }
+    finally {
+        await stopCursorWorkerIfRunning();
+    }
+}
+export async function resumeDagRun(opts) {
+    const located = await locateDagRun(opts.cwd, opts.runId);
+    if (!located) {
+        throw new Error(`dag run not found: ${opts.runId}`);
+    }
+    if (located.lifecycle === "completed") {
+        throw new Error(`dag run ${opts.runId} is already completed`);
+    }
+    if (located.lifecycle === "paused") {
+        throw new Error(`dag run ${opts.runId} is paused; approve before resume`);
+    }
+    const { runDir, state, spec } = await requireActiveDagRun(opts.cwd, opts.runId);
+    if (state.status === "paused") {
+        throw new Error(`dag run ${opts.runId} is paused; approve before resume`);
+    }
+    if (isTerminalDagRunStatus(state.status)) {
+        throw new Error(`dag run ${opts.runId} is already terminal (status=${state.status})`);
+    }
+    const decisionNodeId = state.humanDecisionNodeId;
+    if (!decisionNodeId) {
+        throw new Error(`dag run ${opts.runId} has no human decision checkpoint; was it approved?`);
+    }
+    try {
+        await readHumanApprovalArtifact(runDir, decisionNodeId);
+    }
+    catch {
+        throw new Error(`dag run ${opts.runId} is missing human-approval.json for node ${decisionNodeId}`);
+    }
+    const maxConcurrent = Math.max(1, opts.maxConcurrent ?? 4);
+    state.status = "running";
+    const activeRunDir = getDagRunDir(opts.cwd, "active", state.runId);
+    const completedRunDir = getDagRunDir(opts.cwd, "completed", state.runId);
+    const pausedRunDir = getDagRunDir(opts.cwd, "paused", state.runId);
+    try {
+        return await executeDagCheckpoint({
+            spec,
+            state,
+            ranks: state.ranks,
+            runDir,
+            cwd: state.cwd,
+            maxConcurrent,
+            executeNode: opts.executeNode,
+            observer: opts.observer,
+            activeRunDir,
+            completedRunDir,
+            pausedRunDir,
+        });
+    }
+    finally {
+        await stopCursorWorkerIfRunning();
+    }
+}
+async function executeDagCheckpoint(input) {
+    const { spec, state, ranks, runDir: initialRunDir, cwd, maxConcurrent, completedRunDir, pausedRunDir, } = input;
+    let runDir = initialRunDir;
+    let stateWriteQueue = Promise.resolve();
+    const persistState = async () => {
+        stateWriteQueue = stateWriteQueue.then(() => writeDagRunState(runDir, state));
+        await stateWriteQueue;
+    };
+    const tasksById = new Map(spec.tasks.map((task) => [task.id, task]));
+    const baseExecuteNode = input.executeNode ??
+        createDagNodeExecutor({
+            runDir,
+            runId: state.runId,
+            spec,
+        });
+    let pausedByNodeId;
+    while (true) {
+        pausedByNodeId = await executeDagRanksOnce({
+            spec,
+            state,
+            ranks,
+            tasksById,
+            cwd,
+            runDir,
+            maxConcurrent,
+            baseExecuteNode,
+            customExecuteNode: input.executeNode,
+            observer: input.observer,
+            persistState,
+        });
+        if (pausedByNodeId) {
+            break;
+        }
+        const convergenceDecision = await runConvergencePassController({
+            spec,
+            state,
+            tasksById,
+            runDir,
+            cwd,
+            persistState,
+        });
+        if (convergenceDecision.pausedByNodeId) {
+            pausedByNodeId = convergenceDecision.pausedByNodeId;
+            break;
+        }
+        if (convergenceDecision.retry) {
+            continue;
+        }
+        break;
+    }
+    state.finishedAt = new Date().toISOString();
+    const runDirBeforeTransfer = runDir;
+    if (pausedByNodeId) {
+        state.status = "paused";
+        await persistState();
+        await notifyRunObserver(input.observer, "onRunFinish", state);
+        runDir = await transferDagRunDir(runDir, pausedRunDir);
+    }
+    else {
+        finalizeTerminalRunStatus(state, spec.tasks.length);
+        await persistState();
+        await notifyRunObserver(input.observer, "onRunFinish", state);
+        runDir = await transferDagRunDir(runDir, completedRunDir);
+    }
+    await relocateRunArtifactPaths({
+        runDir,
+        oldRunDir: runDirBeforeTransfer,
+        nodes: state.nodes,
+    });
+    relocateConvergenceArtifactPaths(state, runDirBeforeTransfer, runDir);
+    await persistState();
+    return {
+        title: spec.title,
+        runId: state.runId,
+        status: state.status,
+        ranks,
+        nodes: state.nodes,
+        runDir,
+    };
+}
+async function executeDagRanksOnce(input) {
+    let pausedByNodeId;
+    for (const rank of input.ranks) {
+        const runnable = rank.filter((id) => {
+            const node = input.state.nodes[id];
+            const task = input.tasksById.get(id);
+            if (!node || node.status !== "PENDING")
+                return false;
+            return !shouldSkipNode(node, task, input.state.nodes);
+        });
+        const blocked = rank.filter((id) => {
+            const node = input.state.nodes[id];
+            const task = input.tasksById.get(id);
+            return (node?.status === "PENDING" &&
+                shouldSkipNode(node, task, input.state.nodes));
+        });
+        for (const id of blocked) {
+            const node = input.state.nodes[id];
+            node.status = "SKIPPED";
+            node.skippedReason = conditionSkippedByAncestor(input.tasksById.get(id), input.state.nodes)
+                ? "condition ancestor branch not selected"
+                : "upstream dependency failed or was skipped";
+        }
+        if (blocked.length > 0) {
+            await input.persistState();
+        }
+        const pauseGateRunnable = runnable.filter((id) => {
+            const task = input.tasksById.get(id);
+            return isPauseOnHumanDecisionGate(task);
+        });
+        const regularRunnable = runnable.filter((id) => !pauseGateRunnable.includes(id));
+        const rankWriteGuardedNodeIds = runnable.filter((id) => {
+            const task = input.tasksById.get(id);
+            return task ? isWriteGuardedAgentExecutor(task) : false;
+        });
+        const executeNode = buildRankAwareExecuteNode({
+            baseExecuteNode: input.baseExecuteNode,
+            customExecuteNode: input.customExecuteNode,
+            rankWriteGuardedNodeIds,
+            tasksById: input.tasksById,
+            meta: {
+                runDir: input.runDir,
+                runId: input.state.runId,
+                spec: input.spec,
+            },
+        });
+        for (const nodeId of pauseGateRunnable) {
+            await executeDagNode({
+                nodeId,
+                tasksById: input.tasksById,
+                state: input.state,
+                spec: input.spec,
+                cwd: input.cwd,
+                runDir: input.runDir,
+                executeNode,
+                observer: input.observer,
+                persistState: input.persistState,
+                onPause: (id, pausedAt, pauseReason) => {
+                    pausedByNodeId = id;
+                    input.state.pausedAt = pausedAt;
+                    input.state.pausedByNodeId = id;
+                    input.state.pauseReason = pauseReason;
+                },
+            });
+            if (pausedByNodeId)
+                break;
+        }
+        if (pausedByNodeId)
+            break;
+        await mapConcurrent(regularRunnable, input.maxConcurrent, async (nodeId) => {
+            await executeDagNode({
+                nodeId,
+                tasksById: input.tasksById,
+                state: input.state,
+                spec: input.spec,
+                cwd: input.cwd,
+                runDir: input.runDir,
+                executeNode,
+                observer: input.observer,
+                persistState: input.persistState,
+                onPause: (id, pausedAt, pauseReason) => {
+                    pausedByNodeId = id;
+                    input.state.pausedAt = pausedAt;
+                    input.state.pausedByNodeId = id;
+                    input.state.pauseReason = pauseReason;
+                },
+            });
+        });
+        if (pausedByNodeId)
+            break;
+    }
+    return pausedByNodeId;
+}
+function convergenceChainNodeIds(tasksById) {
+    const repairId = tasksById.has("repair-pi") ? "repair-pi" : "repair-cursor";
+    return [
+        "process-supervisor-pi",
+        "process-gate-shell",
+        repairId,
+        "hard-verify-shell",
+    ];
+}
+const CONVERGENCE_NON_RETRY_FAILURES = new Set([
+    "timeout",
+    "spawn-error",
+    "write-guard",
+    "missing-api-key",
+    "auth",
+    "human-rejected",
+    "decision-gate-requires-human",
+]);
+function shouldEnableDagConvergence(spec) {
+    return (process.env.HARNESS_DAG_CONVERGENCE !== "off" &&
+        spec.convergence?.enabled === true);
+}
+async function runConvergencePassController(input) {
+    const convergence = input.state.convergence;
+    if (!convergence?.enabled)
+        return { retry: false };
+    if (process.env.HARNESS_DAG_CONVERGENCE === "off") {
+        convergence.terminalReason = "feature-flag-off";
+        return { retry: false };
+    }
+    if (!hasConvergenceChain(input.tasksById)) {
+        convergence.terminalReason = "unsupported-dag-shape";
+        return { retry: false };
+    }
+    const hardVerify = input.state.nodes["hard-verify-shell"];
+    if (!hardVerify)
+        return { retry: false };
+    if (hardVerify.status === "FINISHED") {
+        convergence.terminalReason = "hard-verify-pass";
+        await appendConvergenceKnowledgePattern({
+            cwd: input.cwd,
+            state: input.state,
+        });
+        return { retry: false };
+    }
+    if (hardVerify.status !== "ERROR")
+        return { retry: false };
+    const currentPass = convergence.currentPass || 1;
+    const hardFailure = hardVerify.failureCategory ?? "unknown";
+    const passRecord = await buildConvergencePassRecord({
+        pass: currentPass,
+        status: "retrying",
+        reason: "hard-verify-failed",
+        state: input.state,
+        runDir: input.runDir,
+    });
+    if (CONVERGENCE_NON_RETRY_FAILURES.has(hardFailure)) {
+        passRecord.status = "terminal";
+        passRecord.reason = "non-retry-failure";
+        convergence.passHistory.push(passRecord);
+        convergence.terminalReason = "non-retry-failure";
+        await input.persistState();
+        return { retry: false };
+    }
+    if (input.spec.convergence?.pauseOnRegression !== false &&
+        detectConvergenceRegression(convergence.passHistory, passRecord)) {
+        passRecord.status = "paused";
+        passRecord.reason = "regression";
+        convergence.passHistory.push(passRecord);
+        convergence.terminalReason = "regression";
+        const pausedAt = new Date().toISOString();
+        input.state.status = "paused";
+        input.state.pausedAt = pausedAt;
+        input.state.pausedByNodeId = "hard-verify-shell";
+        input.state.pauseReason = "convergence-regression";
+        input.state.failureCategory = "convergence-regression";
+        await input.persistState();
+        return { retry: false, pausedByNodeId: "hard-verify-shell" };
+    }
+    if (currentPass >= convergence.maxPasses) {
+        passRecord.status = "terminal";
+        passRecord.reason = "max-passes";
+        convergence.passHistory.push(passRecord);
+        convergence.terminalReason = "max-passes";
+        await input.persistState();
+        return { retry: false };
+    }
+    convergence.passHistory.push(passRecord);
+    convergence.currentPass = currentPass + 1;
+    await resetConvergenceNodesForNextPass({
+        spec: input.spec,
+        state: input.state,
+        tasksById: input.tasksById,
+    });
+    await input.persistState();
+    return { retry: true };
+}
+function hasConvergenceChain(tasksById) {
+    return convergenceChainNodeIds(tasksById).every((id) => tasksById.has(id));
+}
+async function buildConvergencePassRecord(input) {
+    const hardVerify = input.state.nodes["hard-verify-shell"];
+    const processSupervisor = input.state.nodes["process-supervisor-pi"];
+    const verifyEvidence = hardVerify?.verifyEvidence;
+    return {
+        pass: input.pass,
+        startedAt: hardVerify?.startedAt,
+        finishedAt: new Date().toISOString(),
+        status: input.status,
+        reason: input.reason,
+        hardVerifyStatus: hardVerify?.status,
+        hardVerifyFailureCategory: hardVerify?.failureCategory,
+        processVerdict: parseProcessVerdict(processSupervisor),
+        repairArtifact: processSupervisor?.repairArtifact,
+        verifyPhase: verifyEvidence?.phase,
+        verifyQuota: verifyEvidence?.quota,
+        verifyCommandCount: verifyEvidence?.commandCount,
+        verifyCommandLabels: verifyEvidence?.commandLabels,
+        shellSuccessCount: countSuccessfulShellCommands(hardVerify?.stdout),
+        artifactRefs: await preserveConvergencePassArtifacts({
+            pass: input.pass,
+            state: input.state,
+            runDir: input.runDir,
+        }),
+    };
+}
+async function preserveConvergencePassArtifacts(input) {
+    const passDir = path.join(input.runDir, "convergence", `pass-${input.pass}`);
+    await mkdir(passDir, { recursive: true });
+    const nodeIds = nodesToPreserveForConvergence(input.state);
+    const refs = [];
+    for (const nodeId of nodeIds) {
+        const node = input.state.nodes[nodeId];
+        if (!node || node.status === "PENDING")
+            continue;
+        const preservedNodeRecordPath = path.join(passDir, `${nodeId}.json`);
+        const preservedNodeDir = path.join(passDir, nodeId);
+        await copyIfExists(path.join(input.runDir, `${nodeId}.json`), preservedNodeRecordPath);
+        await copyIfExists(path.join(input.runDir, nodeId), preservedNodeDir);
+        refs.push({
+            nodeId,
+            status: node.status,
+            failureCategory: node.failureCategory,
+            nodeRecordPath: node.nodeRecordPath ?? path.join(input.runDir, `${nodeId}.json`),
+            stdoutArtifactPath: node.stdoutArtifactPath,
+            assistantArtifactPath: node.assistantArtifactPath,
+            preservedNodeRecordPath,
+            preservedNodeDir,
+        });
+    }
+    return refs;
+}
+function nodesToPreserveForConvergence(state) {
+    const repairId = state.nodes["repair-pi"] ? "repair-pi" : "repair-cursor";
+    return [
+        "process-supervisor-pi",
+        "process-gate-shell",
+        repairId,
+        "hard-verify-shell",
+    ].filter((nodeId) => state.nodes[nodeId]);
+}
+async function copyIfExists(from, to) {
+    try {
+        await access(from);
+        await cp(from, to, { recursive: true, force: true });
+    }
+    catch {
+        // Missing artifacts are represented in passHistory by absent files.
+    }
+}
+function parseProcessVerdict(node) {
+    const text = `${node?.assistantText ?? ""}\n${node?.stdout ?? ""}`;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "VERDICT: pass")
+            return "pass";
+        if (trimmed === "VERDICT: request-revision")
+            return "request-revision";
+    }
+    return "unknown";
+}
+function assertRepairArtifactVerdictMatchesSupervisor(input) {
+    const supervisorVerdict = parseProcessVerdict(input.node);
+    if (supervisorVerdict === "unknown")
+        return;
+    if (supervisorVerdict !== input.artifactVerdict) {
+        throw new Error(`repair artifact gate failed: verdict mismatch between supervisor ${supervisorVerdict} and REPAIR_ARTIFACT_JSON ${input.artifactVerdict}`);
+    }
+}
+function countSuccessfulShellCommands(stdout) {
+    if (!stdout)
+        return undefined;
+    const matches = stdout.match(/\|\s*\d+\s*\|\s*true\s*\|/g);
+    if (matches)
+        return matches.length;
+    if (/\|\s*\d+\s*\|\s*false\s*\|/.test(stdout))
+        return 0;
+    const explicit = stdout.match(/(?:passed|success(?:es)?|ok)\s*[=:]\s*(\d+)/i);
+    return explicit ? Number.parseInt(explicit[1], 10) : undefined;
+}
+function detectConvergenceRegression(history, current) {
+    const previous = [...history]
+        .reverse()
+        .find((pass) => pass.shellSuccessCount !== undefined);
+    if (previous?.shellSuccessCount !== undefined &&
+        current.shellSuccessCount !== undefined &&
+        current.shellSuccessCount < previous.shellSuccessCount) {
+        return true;
+    }
+    return isWorseFailureCategory(previous?.hardVerifyFailureCategory, current.hardVerifyFailureCategory);
+}
+function isWorseFailureCategory(previous, current) {
+    const severity = new Map([
+        ["success", 0],
+        ["nonzero-exit", 1],
+        ["unknown", 2],
+        ["timeout", 3],
+        ["spawn-error", 3],
+        ["write-guard", 4],
+    ]);
+    if (!previous || !current)
+        return false;
+    return (severity.get(current) ?? 2) > (severity.get(previous) ?? 2);
+}
+async function appendConvergenceKnowledgePattern(input) {
+    const convergence = input.state.convergence;
+    if (!convergence || convergence.passHistory.length === 0)
+        return;
+    const supervisor = input.state.nodes["process-supervisor-pi"];
+    const hardVerify = input.state.nodes["hard-verify-shell"];
+    const pattern = {
+        schemaVersion: 1,
+        type: "dag-convergence-repair",
+        runId: input.state.runId,
+        recordedAt: new Date().toISOString(),
+        passCount: convergence.currentPass,
+        terminalReason: convergence.terminalReason ?? "hard-verify-pass",
+        processVerdict: parseProcessVerdict(supervisor),
+        repairArtifact: supervisor?.repairArtifact,
+        supervisorStructuredBlock: extractSupervisorStructuredBlock(supervisor),
+        hardVerify: {
+            status: hardVerify?.status,
+            failureCategory: hardVerify?.failureCategory,
+            nodeRecordPath: hardVerify?.nodeRecordPath,
+        },
+        passHistory: convergence.passHistory.map((pass) => ({
+            pass: pass.pass,
+            reason: pass.reason,
+            hardVerifyFailureCategory: pass.hardVerifyFailureCategory,
+            shellSuccessCount: pass.shellSuccessCount,
+        })),
+    };
+    const knowledgeDir = path.join(input.cwd, ".harness", "knowledge");
+    await mkdir(knowledgeDir, { recursive: true });
+    await appendFile(path.join(knowledgeDir, "patterns.jsonl"), `${JSON.stringify(pattern)}\n`, "utf-8");
+}
+function extractSupervisorStructuredBlock(node) {
+    // Legacy compatibility only. New supervisor prompts must emit REPAIR_ARTIFACT_JSON.
+    const text = `${node?.assistantText ?? ""}\n${node?.stdout ?? ""}`;
+    const block = {};
+    for (const key of ["FAILURE_CLASS", "FIX_SCOPE", "INVARIANT"]) {
+        const match = text.match(new RegExp(`^${key}:\\s*(.+)$`, "im"));
+        if (match?.[1])
+            block[key] = match[1].trim();
+    }
+    return block;
+}
+async function resetConvergenceNodesForNextPass(input) {
+    const resetIds = new Set(convergenceChainNodeIds(input.tasksById));
+    for (const id of collectTransitiveDescendantTaskIds(input.spec, "hard-verify-shell")) {
+        const node = input.state.nodes[id];
+        if (node?.status === "SKIPPED")
+            resetIds.add(id);
+    }
+    for (const id of resetIds) {
+        const task = input.tasksById.get(id);
+        if (!task)
+            continue;
+        input.state.nodes[id] = freshNodeRecord(task);
+    }
+}
+function collectTransitiveDescendantTaskIds(spec, rootNodeId) {
+    const childrenByParent = new Map();
+    for (const task of spec.tasks) {
+        for (const parent of task.depends_on) {
+            const children = childrenByParent.get(parent) ?? [];
+            children.push(task.id);
+            childrenByParent.set(parent, children);
+        }
+    }
+    const descendants = new Set();
+    const queue = [...(childrenByParent.get(rootNodeId) ?? [])];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (descendants.has(id))
+            continue;
+        descendants.add(id);
+        queue.push(...(childrenByParent.get(id) ?? []));
+    }
+    return descendants;
+}
+function freshNodeRecord(task) {
+    return {
+        id: task.id,
+        status: "PENDING",
+        executor: task.executor,
+        complexity: task.complexity,
+    };
+}
+function relocateConvergenceArtifactPaths(state, oldRunDir, newRunDir) {
+    const convergence = state.convergence;
+    if (!convergence || oldRunDir === newRunDir)
+        return;
+    const relocate = (value) => value?.startsWith(oldRunDir)
+        ? path.join(newRunDir, path.relative(oldRunDir, value))
+        : value;
+    for (const pass of convergence.passHistory) {
+        for (const ref of pass.artifactRefs) {
+            ref.nodeRecordPath = relocate(ref.nodeRecordPath);
+            ref.stdoutArtifactPath = relocate(ref.stdoutArtifactPath);
+            ref.assistantArtifactPath = relocate(ref.assistantArtifactPath);
+            ref.preservedNodeRecordPath = relocate(ref.preservedNodeRecordPath);
+            ref.preservedNodeDir = relocate(ref.preservedNodeDir);
+        }
+    }
+}
+function findRepairTaskForGate(input) {
+    return Array.from(input.tasksById.values()).find((candidate) => candidate.depends_on.includes(input.gateTask.id) &&
+        candidate.role === "implementer" &&
+        candidate.writePolicy === "exclusive" &&
+        (candidate.executor === "cursor" ||
+            (candidate.executor === "pi" && candidate.toolProfile === "write")));
+}
+function parseSupervisorRepairArtifact(node) {
+    const text = `${node?.assistantText ?? ""}\n${node?.stdout ?? ""}`;
+    return parseRepairArtifactFromText(text);
+}
+function validateRepairArtifactGateBeforeShell(input) {
+    const gate = input.task.shell?.repairArtifactGate;
+    if (!gate)
+        return;
+    const upstream = input.state.nodes[gate.fromNodeId];
+    const parsed = parseSupervisorRepairArtifact(upstream);
+    if (!parsed.ok) {
+        throw new Error(`repair artifact gate failed: ${parsed.reason}`);
+    }
+    assertRepairArtifactVerdictMatchesSupervisor({
+        node: upstream,
+        artifactVerdict: parsed.artifact.verdict,
+    });
+    upstream.repairArtifact = parsed.artifact;
+    const scoped = validateRepairArtifactScope({
+        artifact: parsed.artifact,
+        repairTask: findRepairTaskForGate({
+            tasksById: input.tasksById,
+            gateTask: input.task,
+        }),
+    });
+    if (!scoped.ok) {
+        throw new Error(`repair artifact gate failed: ${scoped.reason}`);
+    }
+}
+function recordRepairArtifactForSupervisorNode(input) {
+    const dependentGate = Object.values(input.state.nodes).find((record) => record.id === "process-gate-shell");
+    if (input.task.id !== "process-supervisor-pi" || !dependentGate)
+        return;
+    const parsed = parseSupervisorRepairArtifact(input.node);
+    if (parsed.ok) {
+        input.node.repairArtifact = parsed.artifact;
+    }
+}
+async function executeDagNode(input) {
+    const { nodeId, tasksById, state, spec, cwd, runDir, executeNode } = input;
+    const task = tasksById.get(nodeId);
+    const node = state.nodes[nodeId];
+    node.status = "RUNNING";
+    node.startedAt = new Date().toISOString();
+    if (task.shell?.verifyEvidence) {
+        node.verifyEvidence = task.shell.verifyEvidence;
+    }
+    await input.persistState();
+    await notifyNodeObserver(input.observer, "onNodeStart", nodeId, state);
+    if (task.dynamicExpansion ||
+        task.dynamicReduction ||
+        task.dynamicCondition ||
+        task.dynamicLoopUntil) {
+        const started = Date.now();
+        try {
+            const result = task.dynamicExpansion
+                ? await executeDynamicMapExpansion({
+                    task,
+                    expansion: task.dynamicExpansion,
+                    tasksById,
+                    state,
+                    spec,
+                    cwd,
+                    runDir,
+                    executeNode,
+                    observer: input.observer,
+                    persistState: input.persistState,
+                })
+                : task.dynamicCondition
+                    ? await executeDynamicCondition({
+                        task,
+                        condition: task.dynamicCondition,
+                        tasksById,
+                        state,
+                    })
+                    : task.dynamicLoopUntil
+                        ? await executeDynamicLoopUntil({
+                            task,
+                            loop: task.dynamicLoopUntil,
+                            tasksById,
+                            state,
+                            spec,
+                            cwd,
+                            runDir,
+                            executeNode,
+                            observer: input.observer,
+                            persistState: input.persistState,
+                        })
+                        : await executeDynamicReduction({
+                            task,
+                            reduction: task.dynamicReduction,
+                            state,
+                            runDir,
+                        });
+            node.durationMs = result.durationMs ?? Date.now() - started;
+            node.stdout = result.stdout;
+            node.stderr = result.stderr;
+            node.failureCategory = result.failureCategory;
+            node.finishedAt = new Date().toISOString();
+            node.status = result.ok ? "FINISHED" : "ERROR";
+        }
+        catch (error) {
+            node.status = "ERROR";
+            node.stderr = error instanceof Error ? error.message : String(error);
+            node.finishedAt = new Date().toISOString();
+            node.durationMs = Date.now() - started;
+        }
+        if (node.status === "FINISHED") {
+            const artifactMeta = await persistLongNodeOutputArtifacts({
+                runDir,
+                nodeId,
+                stdout: node.stdout,
+                assistantText: node.assistantText,
+            });
+            Object.assign(node, artifactMeta);
+        }
+        state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+        await appendNodeLog(runDir, nodeId, state.nodes[nodeId]);
+        await input.persistState();
+        await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+        return;
+    }
+    const { prompt, resolvedSkills } = await buildNodePromptWithResolvedSkillInstructions(spec, task, state.nodes, cwd);
+    node.resolvedSkills = resolvedSkills;
+    await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
+    const model = resolveModelForTask(task, spec.executorModels);
+    const started = Date.now();
+    try {
+        validateRepairArtifactGateBeforeShell({
+            task,
+            tasksById,
+            state,
+        });
+        const result = await executeNode({ task, cwd, model, prompt });
+        node.durationMs = result.durationMs ?? Date.now() - started;
+        node.stdout = result.stdout;
+        node.stderr = result.stderr;
+        node.failureCategory = result.failureCategory;
+        if (result.assistantText !== undefined) {
+            node.assistantText = result.assistantText;
+        }
+        if (result.backend !== undefined)
+            node.backend = result.backend;
+        if (result.sdkAttempted !== undefined) {
+            node.sdkAttempted = result.sdkAttempted;
+        }
+        if (result.tokensUsed !== undefined)
+            node.tokensUsed = result.tokensUsed;
+        if (result.parsedEvents !== undefined) {
+            node.parsedEvents = result.parsedEvents;
+        }
+        recordRepairArtifactForSupervisorNode({
+            task,
+            node,
+            state,
+        });
+        const outputChunk = result.assistantText ?? result.stdout;
+        if (outputChunk.trim()) {
+            await notifyNodeObserver(input.observer, "onNodeOutput", nodeId, state, outputChunk);
+        }
+        node.finishedAt = new Date().toISOString();
+        node.status = result.ok ? "FINISHED" : "ERROR";
+        if (result.ok) {
+            const decisionRecord = await recordDecisionEnvelopeForNode({
+                task,
+                runDir,
+                nodeId,
+                assistantText: node.assistantText ?? result.assistantText,
+            });
+            if (decisionRecord) {
+                node.decisionEnvelope = decisionRecord.nodeRecord;
+                if (!decisionRecord.nodeRecord.parseOk) {
+                    node.status = "ERROR";
+                    node.failureCategory = "decision-envelope-invalid";
+                    node.stderr = [
+                        node.stderr,
+                        ...(decisionRecord.nodeRecord.errors ?? []),
+                    ]
+                        .filter(Boolean)
+                        .join("\n");
+                }
+                else if (shouldPauseOnHumanEscalation(task, decisionRecord.nodeRecord) &&
+                    decisionRecord.envelope) {
+                    const pausedAt = new Date().toISOString();
+                    const nodeArtifactsDir = path.join(runDir, nodeId);
+                    const { jsonPath } = await writeHumanEscalationArtifacts({
+                        nodeArtifactsDir,
+                        runId: state.runId,
+                        nodeId,
+                        envelope: decisionRecord.envelope,
+                        pausedAt,
+                    });
+                    node.pauseReason = "decision-gate-requires-human";
+                    node.escalationArtifactPath = jsonPath;
+                    input.onPause(nodeId, pausedAt, node.pauseReason);
+                }
+            }
+        }
+    }
+    catch (error) {
+        node.status = "ERROR";
+        node.stderr = error instanceof Error ? error.message : String(error);
+        node.finishedAt = new Date().toISOString();
+        node.durationMs = Date.now() - started;
+    }
+    if (node.status === "FINISHED") {
+        const artifactMeta = await persistLongNodeOutputArtifacts({
+            runDir,
+            nodeId,
+            stdout: node.stdout,
+            assistantText: node.assistantText,
+        });
+        Object.assign(node, artifactMeta);
+    }
+    state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+    await appendNodeLog(runDir, nodeId, state.nodes[nodeId]);
+    await input.persistState();
+    await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+}
+function sha256Json(value) {
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify(value))
+        .digest("hex")}`;
+}
+function getNodeOutputAsJson(state, nodeId) {
+    const record = state.nodes[nodeId];
+    if (!record || record.status !== "FINISHED") {
+        throw new Error(`itemsFrom upstream node "${nodeId}" is not finished`);
+    }
+    const raw = record.stdout?.trim() || record.assistantText?.trim();
+    if (!raw) {
+        throw new Error(`itemsFrom upstream node "${nodeId}" has no JSON output`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`itemsFrom upstream node "${nodeId}" output is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function resolveOutputSelector(selector, state) {
+    const match = selector.match(/^\$\.nodes\[['"]([^'"]+)['"]\]\.output(?:\.(.+))?$/);
+    if (!match?.[1]) {
+        throw new Error(`unsupported itemsFrom selector: ${selector}`);
+    }
+    const nodeId = match[1];
+    const pathSuffix = match[2];
+    let current = getNodeOutputAsJson(state, nodeId);
+    if (pathSuffix) {
+        for (const segment of pathSuffix.split(".")) {
+            if (current &&
+                typeof current === "object" &&
+                segment in current) {
+                current = current[segment];
+                continue;
+            }
+            throw new Error(`output selector path not found: ${selector} (missing "${segment}")`);
+        }
+    }
+    return current;
+}
+function resolveItemsFromSelector(selector, state) {
+    let current;
+    try {
+        current = resolveOutputSelector(selector, state);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith("output selector path not found:")) {
+            throw new Error(`itemsFrom path not found: ${selector}`);
+        }
+        throw error;
+    }
+    if (!Array.isArray(current)) {
+        throw new Error(`itemsFrom selector did not resolve to an array: ${selector}`);
+    }
+    return current;
+}
+function parseConditionLiteral(raw) {
+    const trimmed = raw.trim();
+    if ((trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+        (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+        return trimmed.slice(1, -1);
+    }
+    if (trimmed === "true")
+        return true;
+    if (trimmed === "false")
+        return false;
+    if (trimmed === "null")
+        return null;
+    const numeric = Number(trimmed);
+    return Number.isFinite(numeric) ? numeric : trimmed;
+}
+function evaluateConditionExpression(expression, state) {
+    const equality = expression.match(/^\s*(\$\..+?)\s*==\s*(.+?)\s*$/);
+    if (!equality?.[1]) {
+        throw new Error(`unsupported condition expression: ${expression}`);
+    }
+    const actual = resolveOutputSelector(equality[1], state);
+    const expected = parseConditionLiteral(equality[2] ?? "");
+    return actual === expected;
+}
+function evaluateLoopStopExpression(input) {
+    const equality = input.expression.match(/^\s*(\$\..+?)\s*==\s*(.+?)\s*$/);
+    if (!equality?.[1]) {
+        throw new Error(`unsupported loop_until stop expression: ${input.expression}`);
+    }
+    const selector = equality[1];
+    let actual;
+    if (selector.startsWith("$.last.output.")) {
+        actual = lookupPath(input.lastOutput, selector.slice("$.last.output.".length));
+    }
+    else if (selector === "$.iteration") {
+        actual = input.iteration;
+    }
+    else {
+        throw new Error(`unsupported loop_until stop selector: ${selector}`);
+    }
+    const expected = parseConditionLiteral(equality[2] ?? "");
+    return actual === expected;
+}
+function executeDynamicCondition(input) {
+    const started = Date.now();
+    const matchedIndex = input.condition.cases.findIndex((conditionCase) => evaluateConditionExpression(conditionCase.when, input.state));
+    const selected = matchedIndex >= 0
+        ? input.condition.cases[matchedIndex]?.then
+        : input.condition.default;
+    if (!selected) {
+        throw new Error(`condition ${input.task.id} did not match and has no default`);
+    }
+    if (!input.tasksById.has(selected)) {
+        throw new Error(`condition ${input.task.id} selected missing target ${selected}`);
+    }
+    const branchTargets = new Set([
+        ...input.condition.cases.map((conditionCase) => conditionCase.then),
+        ...(input.condition.default ? [input.condition.default] : []),
+    ]);
+    for (const target of branchTargets) {
+        if (target === selected)
+            continue;
+        const record = input.state.nodes[target];
+        if (record?.status === "PENDING") {
+            record.status = "SKIPPED";
+            record.skippedReason = `condition ${input.task.id} selected ${selected}; branch not selected`;
+        }
+    }
+    return {
+        ok: true,
+        stdout: JSON.stringify({
+            workflowNodeId: input.condition.workflowNodeId,
+            selected,
+            matchedCaseIndex: matchedIndex >= 0 ? matchedIndex : undefined,
+            defaulted: matchedIndex < 0,
+        }),
+        stderr: "",
+        failureCategory: "success",
+        durationMs: Date.now() - started,
+    };
+}
+function renderLoopTemplate(template, iteration) {
+    const iterationStatus = iteration >= 2 ? "passed" : "failed";
+    return template
+        .replace(/\{\{\s*iteration\s*\}\}/g, String(iteration))
+        .replace(/\{\{\s*iterationStatus\s*\}\}/g, iterationStatus);
+}
+function buildLoopBodyChildTask(input) {
+    const { parent, bodyTask, iteration, nodeId, bodyIdMap } = input;
+    const mappedDepends = bodyTask.dependsOn.map((depId) => bodyIdMap.get(depId) ?? depId);
+    return {
+        id: nodeId,
+        depends_on: mappedDepends.length > 0 ? mappedDepends : parent.depends_on,
+        complexity: bodyTask.complexity,
+        subtask_prompt: renderLoopTemplate(bodyTask.subtaskPromptTemplate, iteration),
+        executor: bodyTask.executor,
+        role: bodyTask.role,
+        writePolicy: bodyTask.writePolicy,
+        allowedPaths: bodyTask.allowedPaths,
+        forbiddenPaths: bodyTask.forbiddenPaths,
+        writeSet: bodyTask.writeSet,
+        outputContract: bodyTask.outputContract,
+        static: bodyTask.executor === "static"
+            ? {
+                resultMarkdown: bodyTask.staticResultTemplate
+                    ? renderLoopTemplate(bodyTask.staticResultTemplate, iteration)
+                    : "dynamic loop child completed",
+            }
+            : undefined,
+    };
+}
+async function executeDynamicLoopUntil(input) {
+    const started = Date.now();
+    const executedChildren = [];
+    let stopped = false;
+    let stopReason = "";
+    let iterations = 0;
+    for (let iteration = 1; iteration <= input.loop.maxIterations; iteration += 1) {
+        iterations = iteration;
+        const bodyIdMap = new Map(input.loop.bodyTasks.map((bodyTask) => [
+            bodyTask.id,
+            `${input.task.id}-r${iteration}-${bodyTask.id}`,
+        ]));
+        const children = input.loop.bodyTasks.map((bodyTask) => buildLoopBodyChildTask({
+            parent: input.task,
+            loop: input.loop,
+            bodyTask,
+            iteration,
+            nodeId: bodyIdMap.get(bodyTask.id),
+            bodyIdMap,
+        }));
+        for (const child of children) {
+            if (!input.tasksById.has(child.id)) {
+                input.tasksById.set(child.id, child);
+                input.spec.tasks.push(child);
+            }
+            if (!input.state.nodes[child.id]) {
+                input.state.nodes[child.id] = freshNodeRecord(child);
+            }
+        }
+        input.state.ranks.push(children.map((child) => child.id));
+        await writeDagRunSpec(input.runDir, input.spec);
+        await input.persistState();
+        for (const child of children) {
+            await executeDagNode({
+                nodeId: child.id,
+                tasksById: input.tasksById,
+                state: input.state,
+                spec: input.spec,
+                cwd: input.cwd,
+                runDir: input.runDir,
+                executeNode: input.executeNode,
+                observer: input.observer,
+                persistState: input.persistState,
+                onPause: () => {
+                    throw new Error(`dynamic child node ${child.id} requested a human pause; loop_until children do not support pause in v0`);
+                },
+            });
+            executedChildren.push(child.id);
+        }
+        const failedChild = children.find((child) => input.state.nodes[child.id]?.status !== "FINISHED");
+        if (failedChild) {
+            return {
+                ok: false,
+                stdout: JSON.stringify({
+                    workflowNodeId: input.loop.workflowNodeId,
+                    iterations,
+                    stopped: false,
+                    children: executedChildren,
+                }),
+                stderr: `loop_until child failed: ${failedChild.id}`,
+                failureCategory: "dynamic-loop-child-failed",
+                durationMs: Date.now() - started,
+            };
+        }
+        const lastChild = children[children.length - 1];
+        const lastOutput = parseJsonFromText(input.state.nodes[lastChild.id]?.stdout);
+        const matched = input.loop.stopWhenAny.find((expression) => evaluateLoopStopExpression({
+            expression,
+            lastOutput,
+            iteration,
+        }));
+        if (matched) {
+            stopped = true;
+            stopReason = matched;
+            break;
+        }
+    }
+    const manifest = {
+        workflowNodeId: input.loop.workflowNodeId,
+        expandedAt: new Date().toISOString(),
+        maxIterations: input.loop.maxIterations,
+        iterations,
+        stopped,
+        stopReason: stopped ? stopReason : undefined,
+        children: executedChildren.map((nodeId) => ({ nodeId })),
+    };
+    const expansionDir = path.join(input.runDir, "expansions");
+    await mkdir(expansionDir, { recursive: true });
+    await writeFile(path.join(expansionDir, `${input.task.id}.expansion.json`), `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+    return {
+        ok: true,
+        stdout: JSON.stringify({
+            workflowNodeId: input.loop.workflowNodeId,
+            iterations,
+            stopped,
+            stopReason: stopped ? stopReason : undefined,
+            maxIterationsReached: !stopped,
+            children: executedChildren,
+        }),
+        stderr: "",
+        failureCategory: "success",
+        durationMs: Date.now() - started,
+    };
+}
+function lookupPath(value, pathExpression) {
+    let current = value;
+    for (const segment of pathExpression.split(".")) {
+        if (current &&
+            typeof current === "object" &&
+            segment in current) {
+            current = current[segment];
+            continue;
+        }
+        return undefined;
+    }
+    return current;
+}
+function templateValueToString(value) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return String(value);
+    }
+    if (value === null || value === undefined)
+        return "";
+    return JSON.stringify(value);
+}
+function parseJsonFromText(value) {
+    if (!value?.trim())
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function renderDynamicTemplate(template, item, index, itemName) {
+    const primitive = typeof item === "string" ||
+        typeof item === "number" ||
+        typeof item === "boolean"
+        ? String(item)
+        : JSON.stringify(item);
+    return template
+        .replace(/\{\{\s*item\s*\}\}/g, primitive)
+        .replace(new RegExp(`\\{\\{\\s*${itemName}\\s*\\}\\}`, "g"), primitive)
+        .replace(new RegExp(`\\{\\{\\s*${itemName}\\.([A-Za-z0-9_.-]+)\\s*\\}\\}`, "g"), (_match, pathExpression) => templateValueToString(lookupPath(item, pathExpression)))
+        .replace(/\{\{\s*item\.([A-Za-z0-9_.-]+)\s*\}\}/g, (_match, pathExpression) => templateValueToString(lookupPath(item, pathExpression)))
+        .replace(/\{\{\s*itemJson\s*\}\}/g, JSON.stringify(item))
+        .replace(/\{\{\s*index\s*\}\}/g, String(index));
+}
+function renderDynamicPatternList(patterns, item, index, itemName) {
+    return patterns?.map((pattern) => renderDynamicTemplate(pattern, item, index, itemName));
+}
+function buildExpandedChildTask(input) {
+    const { parent, expansion, item, index, nodeId } = input;
+    const child = expansion.childTask;
+    const subtaskPrompt = renderDynamicTemplate(child.subtaskPromptTemplate, item, index, expansion.itemName);
+    const staticResult = child.staticResultTemplate
+        ? renderDynamicTemplate(child.staticResultTemplate, item, index, expansion.itemName)
+        : undefined;
+    return {
+        id: nodeId,
+        depends_on: parent.depends_on,
+        complexity: child.complexity,
+        subtask_prompt: subtaskPrompt,
+        executor: child.executor,
+        role: child.role,
+        writePolicy: child.writePolicy,
+        allowedPaths: renderDynamicPatternList(child.allowedPaths, item, index, expansion.itemName) ?? [],
+        forbiddenPaths: renderDynamicPatternList(child.forbiddenPaths, item, index, expansion.itemName) ?? [],
+        writeSet: renderDynamicPatternList(child.writeSet, item, index, expansion.itemName),
+        outputContract: child.outputContract,
+        static: child.executor === "static"
+            ? { resultMarkdown: staticResult ?? "dynamic child completed" }
+            : undefined,
+    };
+}
+function addExpansionRank(input) {
+    if (input.state.ranks.some((rank) => input.childNodeIds.every((nodeId) => rank.includes(nodeId)))) {
+        return;
+    }
+    const parentRankIndex = input.state.ranks.findIndex((rank) => rank.includes(input.parentNodeId));
+    const insertAt = parentRankIndex >= 0 ? parentRankIndex + 1 : input.state.ranks.length;
+    input.state.ranks.splice(insertAt, 0, input.childNodeIds);
+}
+function normalizedWritePattern(pattern) {
+    return pattern.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function writePatternsOverlap(left, right) {
+    const normalizedLeft = normalizedWritePattern(left);
+    const normalizedRight = normalizedWritePattern(right);
+    if (normalizedLeft === normalizedRight)
+        return true;
+    const leftPrefix = normalizedLeft.replace(/\*\*.*$/, "");
+    const rightPrefix = normalizedRight.replace(/\*\*.*$/, "");
+    return (leftPrefix.length > 0 &&
+        rightPrefix.length > 0 &&
+        (leftPrefix.startsWith(rightPrefix) || rightPrefix.startsWith(leftPrefix)));
+}
+function collectDynamicChildWriteSetConflicts(children) {
+    const conflicts = [];
+    const exclusiveChildren = children.filter((child) => child.writePolicy === "exclusive" && (child.writeSet?.length ?? 0) > 0);
+    for (let i = 0; i < exclusiveChildren.length; i += 1) {
+        for (let j = i + 1; j < exclusiveChildren.length; j += 1) {
+            const left = exclusiveChildren[i];
+            const right = exclusiveChildren[j];
+            for (const leftEntry of left.writeSet ?? []) {
+                for (const rightEntry of right.writeSet ?? []) {
+                    if (writePatternsOverlap(leftEntry, rightEntry)) {
+                        conflicts.push(`${left.id}:${leftEntry} overlaps ${right.id}:${rightEntry}`);
+                    }
+                }
+            }
+        }
+    }
+    return conflicts;
+}
+function resolveRunLocalPath(runDir, ref, label) {
+    if (path.isAbsolute(ref)) {
+        throw new Error(`${label} must be relative to the DAG run directory: ${ref}`);
+    }
+    const runRoot = path.resolve(runDir);
+    const resolved = path.resolve(runRoot, ref);
+    if (resolved !== runRoot && !resolved.startsWith(`${runRoot}${path.sep}`)) {
+        throw new Error(`${label} escapes the DAG run directory: ${ref}`);
+    }
+    return resolved;
+}
+async function executeDynamicMapExpansion(input) {
+    const started = Date.now();
+    const items = resolveItemsFromSelector(input.expansion.itemsFrom, input.state);
+    if (items.length > input.expansion.maxExpandedNodes) {
+        throw new Error(`map_agent ${input.task.id} item count ${items.length} exceeds maxExpandedNodes ${input.expansion.maxExpandedNodes}`);
+    }
+    if (items.length > input.expansion.maxItems) {
+        throw new Error(`map_agent ${input.task.id} item count ${items.length} exceeds maxItems ${input.expansion.maxItems}`);
+    }
+    const childNodeIds = items.map((_, index) => `${input.expansion.childIdPrefix}-${String(index + 1).padStart(4, "0")}`);
+    const children = childNodeIds.map((nodeId, index) => buildExpandedChildTask({
+        parent: input.task,
+        expansion: input.expansion,
+        item: items[index],
+        index,
+        nodeId,
+    }));
+    const writeSetConflicts = collectDynamicChildWriteSetConflicts(children);
+    if (writeSetConflicts.length > 0) {
+        throw new Error(`dynamic map_agent ${input.task.id} expanded overlapping writeSets: ${writeSetConflicts.join("; ")}`);
+    }
+    const workspaceRefs = items.map((item, index) => input.expansion.workspaceTemplate
+        ? renderDynamicTemplate(input.expansion.workspaceTemplate, item, index, input.expansion.itemName)
+        : undefined);
+    for (const workspaceRef of workspaceRefs) {
+        if (!workspaceRef)
+            continue;
+        await mkdir(resolveRunLocalPath(input.runDir, workspaceRef, "workspaceRef"), {
+            recursive: true,
+        });
+    }
+    for (const child of children) {
+        if (!input.tasksById.has(child.id)) {
+            input.tasksById.set(child.id, child);
+            input.spec.tasks.push(child);
+        }
+        if (!input.state.nodes[child.id]) {
+            input.state.nodes[child.id] = freshNodeRecord(child);
+        }
+    }
+    addExpansionRank({
+        state: input.state,
+        parentNodeId: input.task.id,
+        childNodeIds,
+    });
+    await writeDagRunSpec(input.runDir, input.spec);
+    const manifest = {
+        workflowNodeId: input.expansion.workflowNodeId,
+        expandedAt: new Date().toISOString(),
+        itemsFrom: input.expansion.itemsFrom,
+        itemCount: items.length,
+        children: childNodeIds.map((nodeId, index) => ({
+            nodeId,
+            itemRef: `$.items[${index}]`,
+            itemValueHash: sha256Json(items[index]),
+            workspaceRef: workspaceRefs[index],
+        })),
+    };
+    const expansionDir = path.join(input.runDir, "expansions");
+    await mkdir(expansionDir, { recursive: true });
+    await writeFile(path.join(expansionDir, `${input.task.id}.expansion.json`), `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+    await input.persistState();
+    for (const child of children) {
+        const childRecord = input.state.nodes[child.id];
+        if (childRecord?.status === "FINISHED")
+            continue;
+        await executeDagNode({
+            nodeId: child.id,
+            tasksById: input.tasksById,
+            state: input.state,
+            spec: input.spec,
+            cwd: input.cwd,
+            runDir: input.runDir,
+            executeNode: input.executeNode,
+            observer: input.observer,
+            persistState: input.persistState,
+            onPause: () => {
+                throw new Error(`dynamic child node ${child.id} requested a human pause; map_agent children do not support pause in v0`);
+            },
+        });
+    }
+    const failedChildren = childNodeIds.filter((nodeId) => input.state.nodes[nodeId]?.status !== "FINISHED");
+    const aggregate = {
+        workflowNodeId: input.expansion.workflowNodeId,
+        itemCount: items.length,
+        children: childNodeIds.map((nodeId, index) => ({
+            nodeId,
+            item: items[index],
+            workspaceRef: workspaceRefs[index],
+            status: input.state.nodes[nodeId]?.status,
+            stdout: input.state.nodes[nodeId]?.stdout,
+            output: parseJsonFromText(input.state.nodes[nodeId]?.stdout),
+            assistantText: input.state.nodes[nodeId]?.assistantText,
+        })),
+    };
+    return {
+        ok: failedChildren.length === 0,
+        stdout: JSON.stringify(aggregate),
+        stderr: failedChildren.length > 0
+            ? `dynamic map children failed: ${failedChildren.join(", ")}`
+            : "",
+        failureCategory: failedChildren.length > 0 ? "dynamic-expansion-child-failed" : "success",
+        durationMs: Date.now() - started,
+    };
+}
+function parseFindingsFromSelector(selector, state) {
+    const raw = resolveOutputSelector(selector, state);
+    if (!Array.isArray(raw)) {
+        throw new Error(`findings selector did not resolve to an array: ${selector}`);
+    }
+    return raw.map((entry) => {
+        const direct = findingSchema.safeParse(entry);
+        if (direct.success)
+            return direct.data;
+        if (entry && typeof entry === "object") {
+            const output = entry.output;
+            const fromOutput = findingSchema.safeParse(output);
+            if (fromOutput.success)
+                return fromOutput.data;
+            const stdout = entry.stdout;
+            if (typeof stdout === "string") {
+                const fromStdout = findingSchema.safeParse(parseJsonFromText(stdout));
+                if (fromStdout.success)
+                    return fromStdout.data;
+            }
+        }
+        return findingSchema.parse(entry);
+    });
+}
+function parseVerificationFromChildEntry(entry) {
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    const stdout = entry.stdout;
+    if (typeof stdout !== "string" || stdout.trim().length === 0) {
+        return undefined;
+    }
+    return verificationSchema.parse(JSON.parse(stdout));
+}
+function parseVerificationsFromSelector(selector, state) {
+    const raw = resolveOutputSelector(selector, state);
+    if (!Array.isArray(raw)) {
+        throw new Error(`verifications selector did not resolve to an array: ${selector}`);
+    }
+    return raw
+        .map(parseVerificationFromChildEntry)
+        .filter((entry) => Boolean(entry));
+}
+async function executeDynamicReduction(input) {
+    const started = Date.now();
+    if (input.reduction.type !== "verified_findings_report") {
+        throw new Error(`unsupported dynamic reduction: ${input.reduction.type}`);
+    }
+    const findings = parseFindingsFromSelector(input.reduction.findingsFrom, input.state);
+    const verifications = parseVerificationsFromSelector(input.reduction.verificationsFrom, input.state);
+    const nodeDir = path.join(input.runDir, input.task.id);
+    await mkdir(nodeDir, { recursive: true });
+    const refutedFindingsPath = path.join(nodeDir, input.reduction.refutedFindingsArtifactName);
+    const { report, refutedFindings } = buildVerifiedFindingsReport({
+        findings,
+        verifications,
+        refutedFindingsRef: refutedFindingsPath.startsWith(input.runDir)
+            ? repoRelativePath(input.runDir, refutedFindingsPath)
+            : refutedFindingsPath,
+    });
+    await writeFile(refutedFindingsPath, `${JSON.stringify(refutedFindings, null, 2)}\n`, "utf-8");
+    return {
+        ok: true,
+        stdout: JSON.stringify(report),
+        stderr: "",
+        failureCategory: "success",
+        durationMs: Date.now() - started,
+    };
+}
+async function notifyRunObserver(observer, event, state) {
+    try {
+        await observer?.[event]?.(state);
+    }
+    catch {
+        // Observers are derived views; they must not affect canonical DAG execution.
+    }
+}
+async function notifyNodeObserver(observer, event, nodeId, state, chunk) {
+    try {
+        if (event === "onNodeOutput") {
+            await observer?.onNodeOutput?.(nodeId, chunk ?? "", state);
+            return;
+        }
+        await observer?.[event]?.(nodeId, state);
+    }
+    catch {
+        // Observers are derived views; they must not affect canonical DAG execution.
+    }
+}
+function finalizeTerminalRunStatus(state, taskCount) {
+    const finishedCount = Object.values(state.nodes).filter((n) => n.status === "FINISHED").length;
+    const errorCount = Object.values(state.nodes).filter((n) => n.status === "ERROR").length;
+    const conditionSkippedCount = Object.values(state.nodes).filter((n) => n.status === "SKIPPED" && isConditionSkippedReason(n.skippedReason)).length;
+    if (errorCount === 0 && finishedCount + conditionSkippedCount === taskCount) {
+        state.status = "finished";
+    }
+    else if (finishedCount > 0) {
+        state.status = "partial_failed";
+    }
+    else {
+        state.status = "failed";
+    }
+}
+async function stopCursorWorkerIfRunning() {
+    const { isCursorWorkerRunning, stopCursorWorker } = await import("../../executors/cursor-worker-client.js");
+    if (isCursorWorkerRunning()) {
+        await stopCursorWorker();
+    }
+}
+function isWriteGuardedAgentExecutor(task) {
+    return (task.executor === "cursor" ||
+        (task.executor === "pi" && task.toolProfile === "write"));
+}
+function concurrentSiblingWriteSetsForNode(rankWriteGuardedNodeIds, nodeId, tasksById) {
+    if (rankWriteGuardedNodeIds.length <= 1)
+        return [];
+    return rankWriteGuardedNodeIds
+        .filter((id) => id !== nodeId)
+        .map((id) => tasksById.get(id)?.writeSet ?? [])
+        .filter((writeSet) => writeSet.length > 0);
+}
+function buildRankAwareExecuteNode(input) {
+    if (input.customExecuteNode) {
+        return input.baseExecuteNode;
+    }
+    return async (nodeInput) => {
+        if (!isWriteGuardedAgentExecutor(nodeInput.task) || !nodeInput.model) {
+            return input.baseExecuteNode(nodeInput);
+        }
+        const siblingWriteSets = nodeInput.task.writePolicy === "exclusive"
+            ? concurrentSiblingWriteSetsForNode(input.rankWriteGuardedNodeIds, nodeInput.task.id, input.tasksById)
+            : [];
+        const meta = {
+            ...input.meta,
+            concurrentSiblingWriteSets: siblingWriteSets.length > 0 ? siblingWriteSets : undefined,
+            writeGuardAttribution: siblingWriteSets.length > 0 ? "best-effort" : "per-node",
+        };
+        if (nodeInput.task.executor === "pi") {
+            return executeDagPiNode({ ...nodeInput, model: nodeInput.model }, meta);
+        }
+        return executeDagCursorNode({ ...nodeInput, model: nodeInput.model }, meta);
+    };
+}
+function shouldSkipNode(node, task, nodes) {
+    if (!node || node.status !== "PENDING")
+        return false;
+    return task.depends_on.some((depId) => {
+        const dep = nodes[depId];
+        return !dep || dep.status === "ERROR" || dep.status === "SKIPPED";
+    });
+}
+function isConditionSkippedReason(reason) {
+    return Boolean(reason?.startsWith("condition "));
+}
+function conditionSkippedByAncestor(task, nodes) {
+    return task.depends_on.some((depId) => isConditionSkippedReason(nodes[depId]?.skippedReason));
+}
+async function mapConcurrent(items, limit, fn) {
+    const executing = new Set();
+    for (const item of items) {
+        const job = fn(item).finally(() => executing.delete(job));
+        executing.add(job);
+        if (executing.size >= limit) {
+            await Promise.race(executing);
+        }
+    }
+    await Promise.all(executing);
+}
+async function writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills) {
+    if (resolvedSkills.length === 0)
+        return;
+    const nodeDir = path.join(runDir, nodeId);
+    await mkdir(nodeDir, { recursive: true });
+    await writeFile(path.join(nodeDir, "skills.json"), `${JSON.stringify({ resolvedSkills }, null, 2)}\n`, "utf-8");
+}
+async function appendNodeLog(runDir, nodeId, record) {
+    await writeFile(path.join(runDir, `${nodeId}.json`), `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+}