@tea-agent/loop-agent 0.1.0

package/dist/workflows/dag/decision-envelope.js

@@ -0,0 +1,502 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { summarizeDecisionEnvelopeEvidenceCompleteness, } from "./decision-evidence.js";
+import { locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
+export const DECISION_ENVELOPE_FENCE_INFO = "DECISION_ENVELOPE_JSON";
+const decisionGateTypeSchema = z.enum([
+    "plan-gate",
+    "side-effect-gate",
+    "acceptance-gate",
+    "closeout-gate",
+]);
+const decisionScopeSchema = z.enum([
+    "node",
+    "rank",
+    "dag-run",
+    "task",
+    "repo",
+]);
+const decisionValueSchema = z.enum([
+    "auto-approve",
+    "approve-with-constraints",
+    "request-revision",
+    "run-more-verification",
+    "split-followup",
+    "reject",
+    "escalate-to-human",
+    "pause-wait-external",
+]);
+const nextActionSchema = z.enum([
+    "continue",
+    "rerun-implement",
+    "rerun-verify",
+    "run-targeted-check",
+    "split-followup",
+    "pause-and-ask",
+    "abort",
+]);
+const riskLevelSchema = z.enum(["low", "medium", "high", "critical"]);
+const evidenceStatusSchema = z.enum([
+    "verified",
+    "partial",
+    "self-reported",
+    "conflicting",
+    "missing",
+]);
+const humanEscalationOptionSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    risk: z.string().min(1),
+    reason: z.string().min(1),
+});
+const humanEscalationSchema = z.object({
+    question: z.string().min(1),
+    recommendedOption: z.string().min(1),
+    options: z.array(humanEscalationOptionSchema).min(1),
+});
+const evidenceItemSchema = z.object({
+    path: z.string().min(1),
+    kind: z.string().min(1),
+    status: evidenceStatusSchema,
+    summary: z.string().min(1),
+});
+export const decisionEnvelopeSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    gateType: decisionGateTypeSchema,
+    decisionScope: decisionScopeSchema,
+    decision: decisionValueSchema,
+    confidence: z.number().min(0).max(1),
+    riskLevel: riskLevelSchema,
+    requiresHuman: z.boolean(),
+    nextAction: nextActionSchema,
+    policyVersion: z.string().min(1),
+    policyChecks: z.object({
+        mustEscalateFlags: z.array(z.string().min(1)),
+        evidenceComplete: z.boolean(),
+        allowedAutoApprove: z.boolean(),
+    }),
+    rationale: z.array(z.string().min(1)).min(1),
+    evidence: z.array(evidenceItemSchema).min(1),
+    blockingFindings: z.array(z.string().min(1)),
+    requiredRevisions: z.array(z.string().min(1)),
+    riskFlags: z.array(z.string().min(1)),
+    humanEscalation: humanEscalationSchema.nullable(),
+    audit: z
+        .object({
+        runId: z.string().min(1),
+        nodeId: z.string().min(1),
+        model: z.string().min(1),
+        sourceHash: z.string().optional(),
+    })
+        .passthrough(),
+})
+    .strict();
+const DECISION_ENVELOPE_FENCE_RE = /```DECISION_ENVELOPE_JSON[ \t]*\r?\n([\s\S]*?)\r?\n```/g;
+export function extractDecisionEnvelopeFencedBlocks(text) {
+    const blocks = [];
+    if (!text)
+        return blocks;
+    const re = new RegExp(DECISION_ENVELOPE_FENCE_RE.source, DECISION_ENVELOPE_FENCE_RE.flags);
+    for (const match of text.matchAll(re)) {
+        const body = match[1]?.trim();
+        if (body)
+            blocks.push(body);
+    }
+    return blocks;
+}
+export function parseDecisionEnvelopeJson(rawJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawJson);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errors: [
+                `malformed JSON in ${DECISION_ENVELOPE_FENCE_INFO} block: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+        };
+    }
+    const schemaResult = decisionEnvelopeSchema.safeParse(parsed);
+    if (!schemaResult.success) {
+        return {
+            ok: false,
+            errors: schemaResult.error.issues.map((issue) => `schema: ${issue.path.join(".") || "(root)"}: ${issue.message}`),
+        };
+    }
+    const semanticErrors = validateDecisionEnvelopeSemantics(schemaResult.data);
+    if (semanticErrors.length > 0) {
+        return { ok: false, errors: semanticErrors };
+    }
+    return { ok: true, envelope: schemaResult.data };
+}
+export function validateDecisionEnvelopeSemantics(envelope) {
+    const errors = [];
+    if ((envelope.decision === "auto-approve" ||
+        envelope.decision === "approve-with-constraints") &&
+        envelope.requiresHuman) {
+        errors.push(`${envelope.decision} must not set requiresHuman=true`);
+    }
+    if ((envelope.decision === "escalate-to-human" ||
+        envelope.decision === "pause-wait-external" ||
+        envelope.nextAction === "pause-and-ask") &&
+        (!envelope.requiresHuman || envelope.humanEscalation === null)) {
+        errors.push("escalate-to-human, pause-wait-external, or nextAction=pause-and-ask requires requiresHuman=true and humanEscalation object");
+    }
+    if (envelope.requiresHuman && envelope.nextAction !== "pause-and-ask") {
+        errors.push("requiresHuman=true requires nextAction=pause-and-ask");
+    }
+    if (!envelope.requiresHuman && envelope.humanEscalation !== null) {
+        errors.push("requiresHuman=false must not include a blocking humanEscalation question");
+    }
+    if (envelope.humanEscalation) {
+        const optionIds = new Set(envelope.humanEscalation.options.map((option) => option.id));
+        if (!optionIds.has(envelope.humanEscalation.recommendedOption)) {
+            errors.push("humanEscalation.recommendedOption must match one of options[].id");
+        }
+    }
+    if ((envelope.riskLevel === "high" || envelope.riskLevel === "critical") &&
+        envelope.decision === "auto-approve") {
+        const verifiedEvidence = envelope.evidence.filter((item) => item.status === "verified");
+        if (!envelope.policyChecks.allowedAutoApprove ||
+            verifiedEvidence.length === 0) {
+            errors.push("high/critical risk must not auto-approve unless policyChecks.allowedAutoApprove is true and verified evidence exists");
+        }
+    }
+    return errors;
+}
+export function parseDecisionEnvelopeFromText(text, source) {
+    const blocks = extractDecisionEnvelopeFencedBlocks(text);
+    if (blocks.length === 0) {
+        return {
+            ok: false,
+            errors: [`missing ${DECISION_ENVELOPE_FENCE_INFO} fenced block`],
+            source,
+        };
+    }
+    if (blocks.length > 1) {
+        return {
+            ok: false,
+            errors: [
+                `expected exactly one ${DECISION_ENVELOPE_FENCE_INFO} fenced block, found ${blocks.length}`,
+            ],
+            source,
+        };
+    }
+    const parsed = parseDecisionEnvelopeJson(blocks[0]);
+    if (!parsed.ok) {
+        return { ok: false, errors: parsed.errors, source };
+    }
+    return { ok: true, envelope: parsed.envelope, source };
+}
+export async function readOptionalTextFile(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function parseDecisionEnvelopeForNode(input) {
+    const primary = input.assistantText?.trim()
+        ? parseDecisionEnvelopeFromText(input.assistantText, "assistantText")
+        : undefined;
+    if (primary?.ok) {
+        return primary;
+    }
+    if (primary &&
+        primary.errors.some((error) => error.startsWith("expected exactly one"))) {
+        return primary;
+    }
+    if (input.resultSummaryMarkdown?.trim()) {
+        const fallback = parseDecisionEnvelopeFromText(input.resultSummaryMarkdown, "resultSummaryFallback");
+        if (fallback.ok) {
+            return fallback;
+        }
+    }
+    if (primary) {
+        return primary;
+    }
+    if (input.resultSummaryMarkdown?.trim()) {
+        return parseDecisionEnvelopeFromText(input.resultSummaryMarkdown, "resultSummaryFallback");
+    }
+    return {
+        ok: false,
+        errors: [`missing ${DECISION_ENVELOPE_FENCE_INFO} fenced block`],
+    };
+}
+export function toDecisionEnvelopeNodeRecord(result) {
+    if (!result.ok) {
+        return {
+            parseOk: false,
+            errors: result.errors,
+            source: result.source,
+        };
+    }
+    return {
+        parseOk: true,
+        decision: result.envelope.decision,
+        requiresHuman: result.envelope.requiresHuman,
+        nextAction: result.envelope.nextAction,
+        riskLevel: result.envelope.riskLevel,
+        source: result.source,
+    };
+}
+export async function writeDecisionEnvelopeArtifacts(nodeArtifactsDir, result) {
+    await mkdir(nodeArtifactsDir, { recursive: true });
+    if (result.ok) {
+        const envelopePath = path.join(nodeArtifactsDir, "decision.envelope.json");
+        await writeFile(envelopePath, `${JSON.stringify(result.envelope, null, 2)}\n`, "utf-8");
+        return { envelopePath };
+    }
+    const validationPath = path.join(nodeArtifactsDir, "decision.envelope.validation.json");
+    await writeFile(validationPath, `${JSON.stringify({
+        ok: false,
+        source: result.source ?? null,
+        errors: result.errors,
+    }, null, 2)}\n`, "utf-8");
+    return { validationPath };
+}
+export function isDecisionGateEnabled(task) {
+    return task.decisionGate?.enabled === true;
+}
+export function isPauseOnHumanDecisionGate(task) {
+    return (isDecisionGateEnabled(task) && task.decisionGate?.mode === "pause-on-human");
+}
+export function shouldPauseOnHumanEscalation(task, nodeRecord) {
+    return (isPauseOnHumanDecisionGate(task) &&
+        nodeRecord?.parseOk === true &&
+        nodeRecord.requiresHuman === true);
+}
+export async function writeHumanEscalationArtifacts(input) {
+    await mkdir(input.nodeArtifactsDir, { recursive: true });
+    const jsonPath = path.join(input.nodeArtifactsDir, "human-escalation.json");
+    const markdownPath = path.join(input.nodeArtifactsDir, "human-escalation.md");
+    const payload = {
+        schemaVersion: 1,
+        runId: input.runId,
+        nodeId: input.nodeId,
+        decision: input.envelope.decision,
+        requiresHuman: input.envelope.requiresHuman,
+        nextAction: input.envelope.nextAction,
+        riskLevel: input.envelope.riskLevel,
+        humanEscalation: input.envelope.humanEscalation,
+        pausedAt: input.pausedAt,
+    };
+    await writeFile(jsonPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+    const escalation = input.envelope.humanEscalation;
+    const markdownLines = [
+        "# Human escalation",
+        "",
+        `- **Run**: \`${input.runId}\``,
+        `- **Node**: \`${input.nodeId}\``,
+        `- **Decision**: \`${input.envelope.decision}\``,
+        `- **Risk**: \`${input.envelope.riskLevel}\``,
+        `- **Paused at**: ${input.pausedAt}`,
+        "",
+        escalation ? `## Question\n\n${escalation.question}` : "## Question\n\n(none)",
+    ];
+    if (escalation) {
+        markdownLines.push("", `Recommended option: \`${escalation.recommendedOption}\``, "", "## Options");
+        for (const option of escalation.options) {
+            markdownLines.push("", `### ${option.label} (\`${option.id}\`)`, `- Risk: ${option.risk}`, `- Reason: ${option.reason}`);
+        }
+    }
+    await writeFile(markdownPath, `${markdownLines.join("\n")}\n`, "utf-8");
+    return { jsonPath, markdownPath };
+}
+export async function recordDecisionEnvelopeForNode(input) {
+    if (!isDecisionGateEnabled(input.task)) {
+        return undefined;
+    }
+    const resultSummaryMarkdown = await readOptionalTextFile(path.join(input.runDir, input.nodeId, "result.summary.md"));
+    const parseResult = await parseDecisionEnvelopeForNode({
+        assistantText: input.assistantText,
+        resultSummaryMarkdown,
+    });
+    const nodeRecord = toDecisionEnvelopeNodeRecord(parseResult);
+    await writeDecisionEnvelopeArtifacts(path.join(input.runDir, input.nodeId), parseResult);
+    return {
+        nodeRecord,
+        envelope: parseResult.ok ? parseResult.envelope : undefined,
+    };
+}
+export function parseDagDecisionCommandArgs(mode, args) {
+    if (args.length === 0) {
+        throw new Error(`usage: dag decision ${mode} --run-id <id> [--node-id <node-id>]`);
+    }
+    let runId;
+    let nodeId;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--run-id") {
+            runId = args[++i];
+            continue;
+        }
+        if (arg.startsWith("--run-id=")) {
+            runId = arg.slice("--run-id=".length);
+            continue;
+        }
+        if (arg === "--node-id") {
+            nodeId = args[++i];
+            continue;
+        }
+        if (arg.startsWith("--node-id=")) {
+            nodeId = arg.slice("--node-id=".length);
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new Error(`unknown dag decision ${mode} flag: ${arg}`);
+        }
+        throw new Error(`unexpected positional argument: ${arg}`);
+    }
+    if (!runId) {
+        throw new Error(`usage: dag decision ${mode} --run-id <id> [--node-id <node-id>]`);
+    }
+    return { runId, nodeId };
+}
+function buildDecisionEnvelopeInspectNodeSummary(envelope) {
+    return {
+        decision: envelope.decision,
+        requiresHuman: envelope.requiresHuman,
+        nextAction: envelope.nextAction,
+        riskLevel: envelope.riskLevel,
+        gateType: envelope.gateType,
+        confidence: envelope.confidence,
+        blockingFindingsCount: envelope.blockingFindings.length,
+        requiredRevisionsCount: envelope.requiredRevisions.length,
+        riskFlags: envelope.riskFlags,
+        hasHumanEscalation: envelope.humanEscalation !== null,
+        evidence: summarizeDecisionEnvelopeEvidenceCompleteness(envelope),
+    };
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolvePersistedDecisionArtifact(nodeDir) {
+    if (await pathExists(path.join(nodeDir, "decision.envelope.json"))) {
+        return "decision.envelope.json";
+    }
+    if (await pathExists(path.join(nodeDir, "decision.envelope.validation.json"))) {
+        return "decision.envelope.validation.json";
+    }
+    return null;
+}
+async function listDecisionGateNodeIds(input) {
+    const ids = new Set();
+    for (const task of input.specTasks) {
+        if (isDecisionGateEnabled(task)) {
+            ids.add(task.id);
+        }
+    }
+    for (const [nodeId, node] of Object.entries(input.state.nodes)) {
+        if (node.decisionEnvelope !== undefined) {
+            ids.add(nodeId);
+        }
+        const nodeDir = path.join(input.runDir, nodeId);
+        if (await resolvePersistedDecisionArtifact(nodeDir)) {
+            ids.add(nodeId);
+        }
+    }
+    return [...ids].sort();
+}
+export async function inspectDecisionEnvelopeNode(input) {
+    const nodeDir = path.join(input.runDir, input.nodeId);
+    const assistantText = input.nodeRecord?.assistantText;
+    const resultSummaryMarkdown = await readOptionalTextFile(path.join(nodeDir, "result.summary.md"));
+    const parseResult = await parseDecisionEnvelopeForNode({
+        assistantText,
+        resultSummaryMarkdown,
+    });
+    const persistedArtifact = await resolvePersistedDecisionArtifact(nodeDir);
+    const summary = parseResult.ok
+        ? buildDecisionEnvelopeInspectNodeSummary(parseResult.envelope)
+        : {
+            decision: input.nodeRecord?.decisionEnvelope?.decision,
+            requiresHuman: input.nodeRecord?.decisionEnvelope?.requiresHuman,
+            nextAction: input.nodeRecord?.decisionEnvelope?.nextAction,
+            riskLevel: input.nodeRecord?.decisionEnvelope?.riskLevel,
+        };
+    return {
+        nodeId: input.nodeId,
+        parseOk: parseResult.ok,
+        source: parseResult.ok ? parseResult.source : parseResult.source,
+        persistedArtifact,
+        inputs: {
+            assistantText: Boolean(assistantText?.trim()),
+            resultSummaryMarkdown: Boolean(resultSummaryMarkdown?.trim()),
+        },
+        recordSummary: input.nodeRecord?.decisionEnvelope,
+        summary,
+        errors: parseResult.ok ? undefined : parseResult.errors,
+    };
+}
+export async function buildDecisionEnvelopeInspectReport(repoRoot, args, mode) {
+    const located = await locateDagRun(repoRoot, args.runId);
+    if (!located) {
+        throw new Error(`dag run not found: ${args.runId}`);
+    }
+    const { lifecycle, runDir } = located;
+    const state = await readDagRunState(runDir);
+    const spec = await readDagRunSpec(runDir);
+    let nodeIds = await listDecisionGateNodeIds({
+        runDir,
+        specTasks: spec.tasks,
+        state,
+    });
+    if (args.nodeId) {
+        if (!nodeIds.includes(args.nodeId)) {
+            const nodeDir = path.join(runDir, args.nodeId);
+            const hasArtifacts = Boolean(state.nodes[args.nodeId]) ||
+                (await resolvePersistedDecisionArtifact(nodeDir)) !== null;
+            if (!hasArtifacts) {
+                throw new Error(`decision gate node not found for run ${args.runId}: ${args.nodeId}`);
+            }
+            nodeIds = [args.nodeId];
+        }
+        else {
+            nodeIds = [args.nodeId];
+        }
+    }
+    if (nodeIds.length === 0) {
+        throw new Error(`no decision gate nodes found for run ${args.runId}`);
+    }
+    const nodes = [];
+    for (const nodeId of nodeIds) {
+        nodes.push(await inspectDecisionEnvelopeNode({
+            runDir,
+            nodeId,
+            nodeRecord: state.nodes[nodeId],
+        }));
+    }
+    return {
+        mode,
+        runId: args.runId,
+        lifecycle,
+        dryRun: true,
+        advisoryOnly: true,
+        valid: nodes.every((node) => node.parseOk),
+        nodes,
+    };
+}
+export async function runDagDecisionInspect(repoRoot, rawArgs) {
+    const parsed = parseDagDecisionCommandArgs("inspect", rawArgs);
+    const report = await buildDecisionEnvelopeInspectReport(repoRoot, parsed, "inspect");
+    console.log(JSON.stringify(report, null, 2));
+}
+export async function runDagDecisionValidate(repoRoot, rawArgs) {
+    const parsed = parseDagDecisionCommandArgs("validate", rawArgs);
+    const report = await buildDecisionEnvelopeInspectReport(repoRoot, parsed, "validate");
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.valid) {
+        process.exit(1);
+    }
+}

package/dist/workflows/dag/decision-evidence.js

@@ -0,0 +1,153 @@
+export const DAG_DECISION_GATE_EVIDENCE_KIND = "dag-report-derived";
+export const DAG_DECISION_GATE_EVIDENCE_STATUS = "verified";
+export const DAG_DECISION_GATE_ADVISORY_NOTICE = "advisory only, not an execution directive";
+function isFailedRunStatus(status) {
+    return status === "failed" || status === "partial_failed";
+}
+function isActionableNodeForRecovery(node) {
+    return (node.status === "ERROR" ||
+        node.status === "SKIPPED" ||
+        (node.failureCategory !== undefined && node.failureCategory !== "success"));
+}
+function findPrimaryActionableNode(nodes) {
+    return (nodes.find((node) => node.status === "ERROR") ??
+        nodes.find(isActionableNodeForRecovery));
+}
+function resolvePrimaryFailureNode(run) {
+    if (run.pausedByNodeId) {
+        return run.nodes.find((node) => node.nodeId === run.pausedByNodeId);
+    }
+    if (isFailedRunStatus(run.status)) {
+        return findPrimaryActionableNode(run.nodes);
+    }
+    return undefined;
+}
+function resolvePrimaryRecovery(run) {
+    if (run.recoveryRecommendation) {
+        return run.recoveryRecommendation;
+    }
+    const primaryNode = resolvePrimaryFailureNode(run);
+    if (primaryNode?.recoveryRecommendation) {
+        return primaryNode.recoveryRecommendation;
+    }
+    return {
+        action: "none",
+        summary: "No recovery needed.",
+        reason: `${run.runId} finished without a derived recovery recommendation.`,
+        humanRequired: false,
+        autoRetryEligible: false,
+    };
+}
+function buildPrimaryFailure(run, primaryNode) {
+    if (primaryNode) {
+        return {
+            scope: "node",
+            nodeId: primaryNode.nodeId,
+            nodeStatus: primaryNode.status,
+            failureCategory: primaryNode.failureCategory,
+            normalizedFailureCategory: primaryNode.normalizedFailureCategory,
+        };
+    }
+    return {
+        scope: "run",
+        failureCategory: run.failureCategory,
+        normalizedFailureCategory: run.normalizedFailureCategory,
+    };
+}
+function collectDownstreamSkippedNodes(run) {
+    return run.downstreamSkippedNodes.map((node) => ({
+        nodeId: node.nodeId,
+        failureCategory: node.failureCategory,
+        normalizedFailureCategory: node.normalizedFailureCategory,
+    }));
+}
+function dagRunEvidencePath(run) {
+    return `.harness/dag-runs/${run.lifecycle}/${run.runId}/state.json`;
+}
+function formatEvidenceSummary(input) {
+    const { primaryFailure, primaryRecovery } = input;
+    const rawCategory = primaryFailure.failureCategory ?? primaryFailure.nodeStatus ?? "unknown";
+    const normalizedCategory = primaryFailure.normalizedFailureCategory ?? "unknown";
+    const nodeSuffix = primaryFailure.nodeId
+        ? ` primaryFailureNodeId=${primaryFailure.nodeId}`
+        : "";
+    return [
+        `recoveryRecommendation action=${primaryRecovery.action}`,
+        `failureCategory=${rawCategory}`,
+        `normalizedFailureCategory=${normalizedCategory}`,
+        `humanRequired=${primaryRecovery.humanRequired}`,
+        `autoRetryEligible=${primaryRecovery.autoRetryEligible}`,
+        `reason=${primaryRecovery.reason}`,
+        `${DAG_DECISION_GATE_ADVISORY_NOTICE}${nodeSuffix}`,
+    ].join(" ");
+}
+/** Read-only envelope evidence counters for inspect/validate dry-run output. */
+export function summarizeDecisionEnvelopeEvidenceCompleteness(envelope) {
+    const counts = {
+        verified: 0,
+        partial: 0,
+        selfReported: 0,
+        conflicting: 0,
+        missing: 0,
+    };
+    for (const item of envelope.evidence) {
+        switch (item.status) {
+            case "verified":
+                counts.verified += 1;
+                break;
+            case "partial":
+                counts.partial += 1;
+                break;
+            case "self-reported":
+                counts.selfReported += 1;
+                break;
+            case "conflicting":
+                counts.conflicting += 1;
+                break;
+            case "missing":
+                counts.missing += 1;
+                break;
+            default:
+                break;
+        }
+    }
+    return {
+        evidenceCount: envelope.evidence.length,
+        verifiedEvidenceCount: counts.verified,
+        partialEvidenceCount: counts.partial,
+        selfReportedEvidenceCount: counts.selfReported,
+        conflictingEvidenceCount: counts.conflicting,
+        missingEvidenceCount: counts.missing,
+        evidenceComplete: envelope.policyChecks.evidenceComplete,
+        allowedAutoApprove: envelope.policyChecks.allowedAutoApprove,
+        mustEscalateFlags: envelope.policyChecks.mustEscalateFlags,
+    };
+}
+/**
+ * Read-only summary of dag-report facts for Decision Gate prompts.
+ * Does not mutate run state or execute retry/resume.
+ */
+export function buildDagDecisionGateEvidence(run) {
+    const primaryNode = resolvePrimaryFailureNode(run);
+    const primaryFailure = buildPrimaryFailure(run, primaryNode);
+    const primaryRecovery = resolvePrimaryRecovery(run);
+    return {
+        runId: run.runId,
+        lifecycle: run.lifecycle,
+        status: run.status,
+        failureCategory: run.failureCategory,
+        normalizedFailureCategory: run.normalizedFailureCategory,
+        primaryFailure,
+        primaryRecovery,
+        downstreamSkippedNodes: collectDownstreamSkippedNodes(run),
+        evidence: [
+            {
+                path: dagRunEvidencePath(run),
+                kind: DAG_DECISION_GATE_EVIDENCE_KIND,
+                status: DAG_DECISION_GATE_EVIDENCE_STATUS,
+                summary: formatEvidenceSummary({ primaryFailure, primaryRecovery }),
+            },
+        ],
+        advisoryOnly: true,
+    };
+}

package/dist/workflows/dag/decision-gates.js

@@ -0,0 +1 @@
+export * from "./decision-envelope.js";

package/dist/workflows/dag/executor-registry.js

@@ -0,0 +1,25 @@
+import { executeDagCursorNode } from "../../executors/dag-cursor-executor.js";
+import { executeDagPiNode } from "../../executors/dag-pi-executor.js";
+import { executeDagShellNode } from "../../executors/shell-executor.js";
+import { executeDagStaticNode } from "../../executors/dag-static-executor.js";
+function requireModel(input) {
+    if (!input.model) {
+        throw new Error(`executor ${input.task.executor} requires a resolved model`);
+    }
+    return input;
+}
+export const DEFAULT_DAG_EXECUTOR_REGISTRY = {
+    cursor: (input, meta) => executeDagCursorNode(requireModel(input), meta),
+    pi: (input, meta) => executeDagPiNode(requireModel(input), meta),
+    shell: executeDagShellNode,
+    static: executeDagStaticNode,
+};
+export function resolveDagExecutorHandler(executor, registry = DEFAULT_DAG_EXECUTOR_REGISTRY) {
+    return registry[executor];
+}
+export function createDagNodeExecutor(meta, registry = DEFAULT_DAG_EXECUTOR_REGISTRY) {
+    return async (input) => {
+        const handler = resolveDagExecutorHandler(input.task.executor, registry);
+        return handler(input, meta);
+    };
+}

package/dist/workflows/dag/facts.js

@@ -0,0 +1,4 @@
+export * from "./decision-evidence.js";
+export * from "./failure-category.js";
+export * from "./recovery-recommendation.js";
+export * from "../../executors/shell-write-guard.js";