@tea-agent/loop-agent 0.1.0

package/dist/workflows/dag/report.js

@@ -0,0 +1,1019 @@
+import { access, readFile, readdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { resolveCliPath } from "../../shared/path-refs.js";
+import { z } from "zod";
+import { repairArtifactSchema } from "./repair-artifact.js";
+import { dagRunDirExists, getDagRunDir, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
+export const DAG_CLOSEOUT_DRAFT_DISCLAIMER = "> **Advisory only.** Derived from completed run facts. Canonical source remains `dag report --json` and `.harness/dag-runs/completed/<run-id>/`. Do not treat this draft as authoritative.";
+import { dagNormalizedFailureCategorySchema, normalizeDagFailureCategory, } from "./failure-category.js";
+import { DAG_RECOVERY_ACTIONS, planDagRecovery, } from "./recovery-recommendation.js";
+import { dagNodeExecutorSchema, dagNodeStatusSchema, LEGACY_TOP_LEVEL_MODELS_ERROR, parseDagSpec, resolveModelForTask, } from "./types.js";
+export const DAG_REPORT_SCHEMA_VERSION = 1;
+export const DAG_REPORT_SCHEMA_RELATIVE_PATH = "docs/templates/agent-dag-report.schema.json";
+const dagRunLifecycleSchema = z.enum(["active", "paused", "completed"]);
+const dagRunStatusSchema = z.enum([
+    "pending",
+    "running",
+    "finished",
+    "partial_failed",
+    "failed",
+    "paused",
+]);
+const dagRecoveryActionSchema = z.enum(DAG_RECOVERY_ACTIONS);
+const dagArtifactRefSchema = z
+    .object({
+    path: z.string(),
+    exists: z.boolean(),
+})
+    .strict();
+const dagRecoveryRecommendationSchema = z
+    .object({
+    action: dagRecoveryActionSchema,
+    summary: z.string(),
+    reason: z.string(),
+    humanRequired: z.boolean(),
+    autoRetryEligible: z.boolean(),
+    commandHint: z.string().optional(),
+})
+    .strict();
+const dagReportPrimaryFailureSchema = z
+    .object({
+    scope: z.enum(["node", "run"]),
+    nodeId: z.string().optional(),
+    nodeStatus: dagNodeStatusSchema.optional(),
+    failureCategory: z.string().optional(),
+    normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+})
+    .strict();
+const dagReportDownstreamSkippedNodeSchema = z
+    .object({
+    nodeId: z.string(),
+    failureCategory: z.string().optional(),
+    normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+})
+    .strict();
+const dagConvergencePassArtifactRefSchema = z
+    .object({
+    nodeId: z.string(),
+    status: dagNodeStatusSchema,
+    failureCategory: z.string().optional(),
+    nodeRecordPath: z.string().optional(),
+    stdoutArtifactPath: z.string().optional(),
+    assistantArtifactPath: z.string().optional(),
+    preservedNodeRecordPath: z.string().optional(),
+    preservedNodeDir: z.string().optional(),
+})
+    .strict();
+const dagConvergencePassReportSchema = z
+    .object({
+    pass: z.number().int().positive(),
+    startedAt: z.string().optional(),
+    finishedAt: z.string(),
+    status: z.enum(["retrying", "terminal", "paused"]),
+    reason: z.string(),
+    hardVerifyStatus: dagNodeStatusSchema.optional(),
+    hardVerifyFailureCategory: z.string().optional(),
+    processVerdict: z.enum(["pass", "request-revision", "unknown"]).optional(),
+    repairArtifact: repairArtifactSchema.optional(),
+    verifyPhase: z.enum(["intermediate", "final"]).optional(),
+    verifyQuota: z.enum(["1", "3", "full"]).optional(),
+    verifyCommandCount: z.number().int().nonnegative().optional(),
+    verifyCommandLabels: z.array(z.string()).optional(),
+    shellSuccessCount: z.number().int().nonnegative().optional(),
+    artifactRefs: z.array(dagConvergencePassArtifactRefSchema),
+})
+    .strict();
+const dagConvergenceReportSchema = z
+    .object({
+    enabled: z.boolean(),
+    maxPasses: z.number().int().positive(),
+    currentPass: z.number().int().positive(),
+    terminalReason: z.string().optional(),
+    passHistory: z.array(dagConvergencePassReportSchema),
+})
+    .strict();
+const dagNodeDecisionEnvelopeSchema = z
+    .object({
+    parseOk: z.boolean(),
+    decision: z.string().optional(),
+    requiresHuman: z.boolean().optional(),
+    nextAction: z.string().optional(),
+    riskLevel: z.string().optional(),
+    source: z.enum(["assistantText", "resultSummaryFallback"]).optional(),
+    errors: z.array(z.string()).optional(),
+})
+    .passthrough();
+const dagNodeArtifactsReportSchema = z
+    .object({
+    resultSummary: dagArtifactRefSchema,
+    promptRedacted: dagArtifactRefSchema,
+    skills: dagArtifactRefSchema,
+    nodeRecord: dagArtifactRefSchema,
+    decisionEnvelope: dagArtifactRefSchema,
+    decisionEnvelopeValidation: dagArtifactRefSchema,
+    humanEscalationJson: dagArtifactRefSchema,
+    humanEscalationMd: dagArtifactRefSchema,
+    humanApproval: dagArtifactRefSchema,
+    humanRejection: dagArtifactRefSchema,
+})
+    .strict();
+const dagNodeReportRowSchema = z
+    .object({
+    nodeId: z.string(),
+    rank: z.number().int().nonnegative(),
+    order: z.number().int().nonnegative(),
+    executor: dagNodeExecutorSchema,
+    model: z.string().optional(),
+    status: dagNodeStatusSchema,
+    durationMs: z.number().nonnegative().optional(),
+    tokensUsed: z.number().nonnegative().optional(),
+    failureCategory: z.string().optional(),
+    normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
+    backend: z.enum(["sdk", "cli"]).optional(),
+    sdkAttempted: z.boolean().optional(),
+    startedAt: z.string().optional(),
+    finishedAt: z.string().optional(),
+    decisionEnvelope: dagNodeDecisionEnvelopeSchema.optional(),
+    artifacts: dagNodeArtifactsReportSchema,
+})
+    .strict();
+const dagRunReportEntrySchema = z
+    .object({
+    runId: z.string().min(1),
+    title: z.string(),
+    lifecycle: dagRunLifecycleSchema,
+    status: dagRunStatusSchema,
+    runDir: z.string().min(1),
+    startedAt: z.string().min(1),
+    finishedAt: z.string().optional(),
+    failureCategory: z.string().optional(),
+    normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
+    primaryFailure: dagReportPrimaryFailureSchema,
+    primaryRecovery: dagRecoveryRecommendationSchema,
+    downstreamSkippedNodes: z.array(dagReportDownstreamSkippedNodeSchema),
+    convergence: dagConvergenceReportSchema.optional(),
+    pausedByNodeId: z.string().optional(),
+    pauseReason: z.string().optional(),
+    executorJsonl: dagArtifactRefSchema,
+    nodes: z.array(dagNodeReportRowSchema),
+})
+    .strict();
+export const dagReportJsonSchema = z
+    .object({
+    schemaVersion: z.literal(DAG_REPORT_SCHEMA_VERSION),
+    runs: z.array(dagRunReportEntrySchema),
+})
+    .strict();
+export function serializeDagReportJson(report) {
+    return {
+        schemaVersion: DAG_REPORT_SCHEMA_VERSION,
+        runs: report.runs,
+    };
+}
+export function validateDagReportJson(value) {
+    const parsed = dagReportJsonSchema.safeParse(value);
+    if (parsed.success) {
+        return { ok: true, report: parsed.data };
+    }
+    return {
+        ok: false,
+        errors: parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`),
+    };
+}
+export const DAG_REPORT_LIFECYCLE_ORDER = [
+    "active",
+    "paused",
+    "completed",
+];
+export const DAG_PAUSED_LATEST_REPORT_PRESET = {
+    lifecycle: "paused",
+    latest: true,
+};
+export { DAG_RECOVERY_ACTIONS };
+export async function probeArtifact(filePath) {
+    try {
+        await access(filePath);
+        return { path: filePath, exists: true };
+    }
+    catch {
+        return { path: filePath, exists: false };
+    }
+}
+export async function buildNodeArtifactsReport(runDir, nodeId) {
+    const nodeDir = path.join(runDir, nodeId);
+    const artifact = (name) => probeArtifact(path.join(nodeDir, name));
+    return {
+        resultSummary: await artifact("result.summary.md"),
+        promptRedacted: await artifact("prompt.redacted.md"),
+        skills: await artifact("skills.json"),
+        nodeRecord: await probeArtifact(path.join(runDir, `${nodeId}.json`)),
+        decisionEnvelope: await artifact("decision.envelope.json"),
+        decisionEnvelopeValidation: await artifact("decision.envelope.validation.json"),
+        humanEscalationJson: await artifact("human-escalation.json"),
+        humanEscalationMd: await artifact("human-escalation.md"),
+        humanApproval: await artifact("human-approval.json"),
+        humanRejection: await artifact("human-rejection.json"),
+    };
+}
+function taskById(spec) {
+    return new Map(spec.tasks.map((task) => [task.id, task]));
+}
+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 findPrimaryActionableNodeForRecovery(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 findPrimaryActionableNodeForRecovery(run.nodes);
+    }
+    return undefined;
+}
+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 resolvePrimaryRecovery(run, primaryNode) {
+    if (run.recoveryRecommendation) {
+        return run.recoveryRecommendation;
+    }
+    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 collectTransitiveDescendantNodeIds(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 nodeId = queue.shift();
+        if (descendants.has(nodeId))
+            continue;
+        descendants.add(nodeId);
+        queue.push(...(childrenByParent.get(nodeId) ?? []));
+    }
+    return descendants;
+}
+function collectDownstreamSkippedNodes(nodes, spec, primaryNode) {
+    const skippedNodes = nodes.filter((node) => node.status === "SKIPPED");
+    const downstream = primaryNode
+        ? skippedNodes.filter((node) => collectTransitiveDescendantNodeIds(spec, primaryNode.nodeId).has(node.nodeId))
+        : skippedNodes;
+    return downstream.map((node) => ({
+        nodeId: node.nodeId,
+        failureCategory: node.failureCategory,
+        normalizedFailureCategory: node.normalizedFailureCategory,
+    }));
+}
+function isFailedReportRun(run) {
+    return (run.status === "failed" ||
+        run.status === "partial_failed" ||
+        run.status === "paused" ||
+        (run.primaryRecovery.action !== "none" &&
+            run.primaryRecovery.action !== "monitor"));
+}
+export function filterDagReportRuns(runs, options) {
+    let filtered = runs;
+    if (options.failedOnly) {
+        filtered = filtered.filter(isFailedReportRun);
+    }
+    if (options.action) {
+        filtered = filtered.filter((run) => run.primaryRecovery.action === options.action);
+    }
+    if (options.latest && filtered.length > 0) {
+        const latest = [...filtered].sort((left, right) => {
+            const startedCompare = left.startedAt.localeCompare(right.startedAt);
+            if (startedCompare !== 0)
+                return startedCompare;
+            return left.runId.localeCompare(right.runId);
+        });
+        return [latest[latest.length - 1]];
+    }
+    return filtered;
+}
+export async function buildDagRunReportEntry(input) {
+    const tasks = taskById(input.spec);
+    const nodes = [];
+    for (let rank = 0; rank < input.state.ranks.length; rank += 1) {
+        const rankNodes = input.state.ranks[rank] ?? [];
+        for (let order = 0; order < rankNodes.length; order += 1) {
+            const nodeId = rankNodes[order];
+            const node = input.state.nodes[nodeId];
+            if (!node)
+                continue;
+            const task = tasks.get(nodeId);
+            const normalizedFailureCategory = normalizeDagFailureCategory(node.failureCategory, node.status);
+            nodes.push({
+                nodeId,
+                rank,
+                order,
+                executor: node.executor,
+                model: task
+                    ? resolveModelForTask(task, input.spec.executorModels)
+                    : undefined,
+                status: node.status,
+                durationMs: node.durationMs,
+                tokensUsed: node.tokensUsed,
+                failureCategory: node.failureCategory,
+                normalizedFailureCategory,
+                recoveryRecommendation: planDagRecovery({
+                    status: node.status,
+                    normalizedFailureCategory,
+                    failureCategory: node.failureCategory,
+                    nodeId,
+                    runId: input.state.runId,
+                    lifecycle: input.lifecycle,
+                    runStatus: input.state.status,
+                }),
+                backend: node.backend,
+                sdkAttempted: node.sdkAttempted,
+                startedAt: node.startedAt,
+                finishedAt: node.finishedAt,
+                decisionEnvelope: node.decisionEnvelope,
+                artifacts: await buildNodeArtifactsReport(input.runDir, nodeId),
+            });
+        }
+    }
+    const normalizedFailureCategory = normalizeDagFailureCategory(input.state.failureCategory, input.state.status);
+    const pausedNode = input.state.pausedByNodeId
+        ? input.state.nodes[input.state.pausedByNodeId]
+        : undefined;
+    const firstActionableNode = isFailedRunStatus(input.state.status)
+        ? findPrimaryActionableNodeForRecovery(nodes)
+        : undefined;
+    const runRecoverySource = pausedNode
+        ? {
+            status: input.state.status,
+            normalizedFailureCategory: normalizeDagFailureCategory(pausedNode.failureCategory, pausedNode.status),
+            failureCategory: pausedNode.failureCategory,
+            nodeId: input.state.pausedByNodeId,
+        }
+        : firstActionableNode
+            ? {
+                status: firstActionableNode.status,
+                normalizedFailureCategory: firstActionableNode.normalizedFailureCategory ??
+                    normalizeDagFailureCategory(firstActionableNode.failureCategory, firstActionableNode.status),
+                failureCategory: firstActionableNode.failureCategory,
+                nodeId: firstActionableNode.nodeId,
+            }
+            : {
+                status: input.state.status,
+                normalizedFailureCategory,
+                failureCategory: input.state.failureCategory,
+            };
+    const recoveryRecommendation = planDagRecovery({
+        ...runRecoverySource,
+        runId: input.state.runId,
+        lifecycle: input.lifecycle,
+        runStatus: input.state.status,
+    });
+    const partialEntry = {
+        runId: input.state.runId,
+        title: input.state.title,
+        lifecycle: input.lifecycle,
+        status: input.state.status,
+        runDir: input.runDir,
+        startedAt: input.state.startedAt,
+        finishedAt: input.state.finishedAt,
+        failureCategory: input.state.failureCategory,
+        normalizedFailureCategory,
+        recoveryRecommendation,
+        pausedByNodeId: input.state.pausedByNodeId,
+        pauseReason: input.state.pauseReason,
+        nodes,
+    };
+    const primaryNode = resolvePrimaryFailureNode(partialEntry);
+    return {
+        ...partialEntry,
+        primaryFailure: buildPrimaryFailure(partialEntry, primaryNode),
+        primaryRecovery: resolvePrimaryRecovery(partialEntry, primaryNode),
+        downstreamSkippedNodes: collectDownstreamSkippedNodes(nodes, input.spec, primaryNode),
+        convergence: input.state.convergence,
+        executorJsonl: await probeArtifact(path.join(input.runDir, "executor.jsonl")),
+    };
+}
+async function readDagRunSpecForReport(runDir) {
+    try {
+        return await readDagRunSpec(runDir);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!message.includes(LEGACY_TOP_LEVEL_MODELS_ERROR)) {
+            throw err;
+        }
+        const raw = JSON.parse(await readFile(path.join(runDir, "run.json"), "utf-8"));
+        delete raw.models;
+        return parseDagSpec(raw);
+    }
+}
+async function readLocatedRun(located) {
+    const [state, spec] = await Promise.all([
+        readDagRunState(located.runDir),
+        readDagRunSpecForReport(located.runDir),
+    ]);
+    return buildDagRunReportEntry({
+        runDir: located.runDir,
+        lifecycle: located.lifecycle,
+        state,
+        spec,
+    });
+}
+async function listRunsInLifecycle(repoRoot, lifecycle) {
+    const lifecycleDir = getDagRunDir(repoRoot, lifecycle, "");
+    try {
+        await access(lifecycleDir);
+    }
+    catch {
+        return [];
+    }
+    const entries = await readdir(lifecycleDir, { withFileTypes: true });
+    const located = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const runDir = path.join(lifecycleDir, entry.name);
+        const statePath = path.join(runDir, "state.json");
+        try {
+            await access(statePath);
+        }
+        catch {
+            continue;
+        }
+        located.push({
+            lifecycle,
+            runDir,
+            runId: entry.name,
+        });
+    }
+    return located;
+}
+async function sortLocatedRuns(located) {
+    const withStartedAt = await Promise.all(located.map(async (entry) => {
+        try {
+            const state = await readDagRunState(entry.runDir);
+            return { entry, startedAt: state.startedAt };
+        }
+        catch {
+            return { entry, startedAt: "" };
+        }
+    }));
+    return withStartedAt
+        .sort((left, right) => {
+        const startedCompare = left.startedAt.localeCompare(right.startedAt);
+        if (startedCompare !== 0)
+            return startedCompare;
+        return left.entry.runId.localeCompare(right.entry.runId);
+    })
+        .map((item) => item.entry);
+}
+export async function listLocatedDagRuns(repoRoot, filter = "all") {
+    const lifecycles = filter === "all" ? DAG_REPORT_LIFECYCLE_ORDER : [filter];
+    const located = [];
+    for (const lifecycle of lifecycles) {
+        const runs = await listRunsInLifecycle(repoRoot, lifecycle);
+        located.push(...(await sortLocatedRuns(runs)));
+    }
+    return located;
+}
+async function locateRunForReport(repoRoot, runId, filter) {
+    if (filter === "all") {
+        const located = await locateDagRun(repoRoot, runId);
+        if (!located) {
+            throw new Error(`dag run not found: ${runId}`);
+        }
+        return { ...located, runId };
+    }
+    const runDir = getDagRunDir(repoRoot, filter, runId);
+    if (!(await dagRunDirExists(runDir))) {
+        throw new Error(`dag run not found: ${runId}`);
+    }
+    return { lifecycle: filter, runDir, runId };
+}
+export async function buildDagReport(options) {
+    const filter = options.lifecycle ?? "all";
+    const located = options.runId
+        ? [await locateRunForReport(options.repoRoot, options.runId, filter)]
+        : await listLocatedDagRuns(options.repoRoot, filter);
+    const runs = await Promise.all(located.map((entry) => readLocatedRun(entry)));
+    return {
+        runs: filterDagReportRuns(runs, {
+            failedOnly: options.failedOnly,
+            latest: options.latest,
+            action: options.action,
+        }),
+    };
+}
+function formatDuration(durationMs) {
+    if (durationMs === undefined)
+        return "-";
+    if (durationMs < 1000)
+        return `${durationMs}ms`;
+    return `${(durationMs / 1000).toFixed(1)}s`;
+}
+function formatTokens(tokensUsed) {
+    return tokensUsed === undefined ? "-" : String(tokensUsed);
+}
+function formatArtifactFlags(artifacts) {
+    const flags = [];
+    if (artifacts.resultSummary.exists)
+        flags.push("summary");
+    if (artifacts.promptRedacted.exists)
+        flags.push("prompt");
+    if (artifacts.skills.exists)
+        flags.push("skills");
+    if (artifacts.nodeRecord.exists)
+        flags.push("node-json");
+    if (artifacts.decisionEnvelope.exists)
+        flags.push("decision");
+    if (artifacts.decisionEnvelopeValidation.exists)
+        flags.push("decision-validation");
+    if (artifacts.humanEscalationJson.exists)
+        flags.push("escalation-json");
+    if (artifacts.humanEscalationMd.exists)
+        flags.push("escalation-md");
+    if (artifacts.humanApproval.exists)
+        flags.push("approval");
+    if (artifacts.humanRejection.exists)
+        flags.push("rejection");
+    return flags.length > 0 ? flags.join(",") : "-";
+}
+function formatTimestamp(value) {
+    return value ?? "—";
+}
+function formatRunDuration(startedAt, finishedAt) {
+    if (!finishedAt)
+        return "—";
+    const started = Date.parse(startedAt);
+    const finished = Date.parse(finishedAt);
+    if (!Number.isFinite(started) || !Number.isFinite(finished))
+        return "—";
+    return formatDuration(Math.max(0, finished - started));
+}
+function summarizeNodeStatuses(nodes) {
+    const total = nodes.length;
+    const finished = nodes.filter((node) => node.status === "FINISHED").length;
+    const failed = nodes.filter((node) => node.status === "ERROR").length;
+    const skipped = nodes.filter((node) => node.status === "SKIPPED").length;
+    const pending = nodes.filter((node) => node.status === "PENDING").length;
+    return `${total} total / ${finished} finished / ${failed} failed / ${skipped} skipped / ${pending} pending`;
+}
+function hasArtifact(artifacts) {
+    return Object.values(artifacts).some((artifact) => artifact.exists);
+}
+function failureRows(run) {
+    return run.nodes.filter((node) => node.status === "ERROR" ||
+        (node.failureCategory !== undefined &&
+            node.failureCategory !== "success"));
+}
+function formatFailureCategoryLabel(node) {
+    const raw = node.failureCategory ?? node.status;
+    const normalized = node.normalizedFailureCategory;
+    if (normalized && normalized !== raw) {
+        return `${raw} (normalized: ${normalized})`;
+    }
+    return String(raw);
+}
+function primaryRecoveryRecommendation(run) {
+    return run.primaryRecovery;
+}
+function suggestedNextAction(run) {
+    const humanNodes = run.nodes.filter((node) => node.decisionEnvelope?.requiresHuman === true);
+    const humanSuffix = humanNodes.length > 0
+        ? ` Human escalation detected for ${humanNodes.map((node) => node.nodeId).join(", ")}.`
+        : "";
+    const recommendation = primaryRecoveryRecommendation(run);
+    if (recommendation.action !== "none") {
+        const pausedHint = run.status === "paused" && run.pausedByNodeId
+            ? ` Paused at node ${run.pausedByNodeId}.`
+            : "";
+        const failedHint = run.primaryFailure.scope === "node" && run.primaryFailure.nodeId
+            ? ` Primary node: ${run.primaryFailure.nodeId}.`
+            : "";
+        return `${recommendation.summary} [${recommendation.action}]${pausedHint}${failedHint}${humanSuffix}`;
+    }
+    return `Run complete. Review result summaries.${humanSuffix}`;
+}
+function formatPrimaryFailureSection(run) {
+    const failure = run.primaryFailure;
+    if (failure.scope === "node" && failure.nodeId) {
+        return [
+            `- **Node**: ${failure.nodeId} (${failure.nodeStatus ?? "unknown"})`,
+            `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+        ];
+    }
+    return [
+        `- **Scope**: run`,
+        `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+    ];
+}
+function formatPrimaryRecoverySection(run) {
+    const rec = run.primaryRecovery;
+    return [
+        `- **Action**: \`${rec.action}\``,
+        `- **Summary**: ${rec.summary}`,
+        `- **Reason**: ${rec.reason}`,
+        `- **Human Required**: ${rec.humanRequired}`,
+        `- **Auto Retry Eligible**: ${rec.autoRetryEligible}`,
+        rec.commandHint ? `- **Command Hint**: ${rec.commandHint}` : undefined,
+    ].filter((line) => line !== undefined);
+}
+function formatDownstreamSkippedSection(run) {
+    if (run.downstreamSkippedNodes.length === 0) {
+        return ["No blocked downstream or skipped nodes."];
+    }
+    return run.downstreamSkippedNodes.map((node) => `- **${node.nodeId}**: ${node.failureCategory ?? "-"} (normalized: ${node.normalizedFailureCategory ?? "-"})`);
+}
+function formatConvergenceSummary(run) {
+    if (!run.convergence)
+        return [];
+    const convergence = run.convergence;
+    const lines = [
+        `- convergence: enabled=${convergence.enabled}, pass=${convergence.currentPass}/${convergence.maxPasses}, terminal=${convergence.terminalReason ?? "-"}`,
+    ];
+    for (const pass of convergence.passHistory) {
+        const verifySummary = pass.verifyPhase || pass.verifyQuota || pass.verifyCommandCount !== undefined
+            ? `, verify=${pass.verifyPhase ?? "-"} quota=${pass.verifyQuota ?? "-"} commands=${pass.verifyCommandCount ?? "-"}`
+            : "";
+        lines.push(`- pass ${pass.pass}: ${pass.status}, reason=${pass.reason}, hardVerify=${pass.hardVerifyStatus ?? "-"}(${pass.hardVerifyFailureCategory ?? "-"})${verifySummary}, artifacts=${pass.artifactRefs.length}`);
+    }
+    return lines;
+}
+function formatRecommendedOperatorAction(run) {
+    const rec = run.primaryRecovery;
+    if (rec.action === "none" || rec.action === "monitor") {
+        return [
+            "No operator recovery action required; review run artifacts as needed.",
+        ];
+    }
+    const lines = [`${rec.summary} [${rec.action}]`];
+    if (rec.commandHint) {
+        lines.push(`Hint: ${rec.commandHint}`);
+    }
+    if (rec.humanRequired) {
+        lines.push("Human input is required before proceeding.");
+    }
+    return lines.map((line) => `- ${line}`);
+}
+function formatRecoveryPlanSection(run) {
+    return [
+        "### Primary Failure",
+        ...formatPrimaryFailureSection(run),
+        "",
+        "### Recovery Action",
+        ...formatPrimaryRecoverySection(run),
+        "",
+        "### Blocked Downstream / Skipped Nodes",
+        ...formatDownstreamSkippedSection(run),
+        "",
+        "### Recommended Operator Action",
+        ...formatRecommendedOperatorAction(run),
+    ];
+}
+export function formatDagReportMarkdown(report) {
+    if (report.runs.length === 0) {
+        return "No DAG runs matched the report filter.\n";
+    }
+    const sections = report.runs.map((run) => {
+        const header = [
+            `## ${run.runId}`,
+            "",
+            `- lifecycle: ${run.lifecycle}`,
+            `- status: ${run.status}`,
+            `- title: ${run.title}`,
+            `- runDir: ${run.runDir}`,
+            `- startedAt: ${run.startedAt}`,
+            `- finishedAt: ${run.finishedAt ?? "-"}`,
+            `- executorJsonl: ${run.executorJsonl.path} (${run.executorJsonl.exists ? "exists" : "missing"})`,
+            ...formatConvergenceSummary(run),
+            "",
+            "| rank | order | node | executor | model | status | duration | tokens | failure | normalized | action | backend | sdk | artifacts |",
+            "| ---: | ----: | --- | --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- | --- |",
+        ];
+        for (const node of run.nodes) {
+            header.push(`| ${node.rank} | ${node.order} | ${node.nodeId} | ${node.executor} | ${node.model ?? "-"} | ${node.status} | ${formatDuration(node.durationMs)} | ${formatTokens(node.tokensUsed)} | ${node.failureCategory ?? "-"} | ${node.normalizedFailureCategory ?? "-"} | ${node.recoveryRecommendation?.action ?? "-"} | ${node.backend ?? "-"} | ${node.sdkAttempted === undefined ? "-" : node.sdkAttempted ? "yes" : "no"} | ${formatArtifactFlags(node.artifacts)} |`);
+        }
+        header.push("");
+        return header.join("\n");
+    });
+    return ["# DAG Run Report", "", ...sections].join("\n");
+}
+function formatFailureSection(run) {
+    const failures = failureRows(run);
+    if (failures.length === 0)
+        return ["No failed nodes."];
+    return failures.map((node) => {
+        const decision = node.decisionEnvelope;
+        const decisionText = decision
+            ? ` decision=${decision.decision ?? "-"}, risk=${decision.riskLevel ?? "-"}, requiresHuman=${decision.requiresHuman === undefined ? "-" : String(decision.requiresHuman)}`
+            : "";
+        return `- **${node.nodeId}**: ${formatFailureCategoryLabel(node)} (${formatDuration(node.durationMs)})${decisionText}`;
+    });
+}
+function formatArtifactsSection(run) {
+    const rows = run.nodes
+        .filter((node) => hasArtifact(node.artifacts))
+        .map((node) => `- **${node.nodeId}**: ${formatArtifactFlags(node.artifacts)}`);
+    return rows.length > 0 ? rows : ["No node artifacts found."];
+}
+export function formatDagReportHandoffMarkdown(report) {
+    if (report.runs.length === 0) {
+        return "# Agent DAG Handoff Report\n\nNo DAG runs matched the report filter.\n";
+    }
+    const sections = report.runs.map((run) => {
+        const lines = [
+            `# Agent DAG Handoff Report: ${run.runId}`,
+            "",
+            "## Summary",
+            `- **Title**: ${run.title}`,
+            `- **Run ID**: ${run.runId}`,
+            `- **Lifecycle**: ${run.lifecycle}`,
+            `- **Status**: ${run.status}`,
+            run.failureCategory
+                ? `- **Failure (raw/normalized)**: ${run.failureCategory} / ${run.normalizedFailureCategory ?? "-"}`
+                : undefined,
+            `- **Started**: ${formatTimestamp(run.startedAt)}`,
+            `- **Finished**: ${formatTimestamp(run.finishedAt)}`,
+            `- **Duration**: ${formatRunDuration(run.startedAt, run.finishedAt)}`,
+            `- **Nodes**: ${summarizeNodeStatuses(run.nodes)}`,
+            `- **Run Dir**: ${run.runDir}`,
+            ...formatConvergenceSummary(run),
+            "",
+            "## Node Timeline",
+        ];
+        for (const node of run.nodes) {
+            lines.push(`### ${node.nodeId}`, `- **Rank/Order**: ${node.rank}/${node.order}`, `- **Status**: ${node.status}`, node.failureCategory
+                ? `- **Failure (raw/normalized)**: ${node.failureCategory} / ${node.normalizedFailureCategory ?? "-"}`
+                : "", `- **Executor**: ${node.executor}${node.backend ? ` (backend: ${node.backend})` : ""}`, `- **Model**: ${node.model ?? "—"}`, `- **Duration**: ${formatDuration(node.durationMs)}`, `- **Tokens**: ${formatTokens(node.tokensUsed)}`, `- **Started**: ${formatTimestamp(node.startedAt)}`, `- **Finished**: ${formatTimestamp(node.finishedAt)}`, "");
+        }
+        lines.push("## Failures", ...formatFailureSection(run), "", "## Recovery Plan", ...formatRecoveryPlanSection(run), "", "## Artifacts", ...formatArtifactsSection(run), "", "## Suggested Next Action", `- ${suggestedNextAction(run)}`, "");
+        return lines
+            .filter((line) => line !== undefined)
+            .join("\n");
+    });
+    return sections.join("\n---\n");
+}
+export function resolveCloseoutDraftOutputPath(repoRoot, outputPath) {
+    return resolveCliPath(outputPath, repoRoot);
+}
+export function defaultCloseoutDraftOutputPath(runId) {
+    return path.join(os.tmpdir(), `${runId}-closeout-draft.md`);
+}
+export function assertCloseoutDraftOutputPathAllowed(repoRoot, outputPath) {
+    const resolved = resolveCloseoutDraftOutputPath(repoRoot, outputPath);
+    const harnessRoot = path.resolve(repoRoot, ".harness");
+    const dagRunsRoot = path.resolve(repoRoot, ".harness", "dag-runs");
+    const underHarness = resolved === harnessRoot ||
+        resolved.startsWith(`${harnessRoot}${path.sep}`);
+    if (!underHarness) {
+        return;
+    }
+    const underDagRuns = resolved === dagRunsRoot ||
+        resolved.startsWith(`${dagRunsRoot}${path.sep}`);
+    if (underDagRuns) {
+        throw new Error(`closeout draft output must not target .harness/dag-runs: ${outputPath}`);
+    }
+    throw new Error(`closeout draft output must not target .harness: ${outputPath}`);
+}
+function formatCloseoutNodeStatusTable(run) {
+    const lines = [
+        "| rank | node | executor | status | failure | normalized | duration |",
+        "| ---: | --- | --- | --- | --- | --- | --- |",
+    ];
+    for (const node of run.nodes) {
+        lines.push(`| ${node.rank} | ${node.nodeId} | ${node.executor} | ${node.status} | ${node.failureCategory ?? "-"} | ${node.normalizedFailureCategory ?? "-"} | ${formatDuration(node.durationMs)} |`);
+    }
+    return lines;
+}
+function formatCloseoutArtifactRefs(artifacts) {
+    const refs = [];
+    if (artifacts.resultSummary.exists)
+        refs.push(`summary:${artifacts.resultSummary.path}`);
+    if (artifacts.nodeRecord.exists)
+        refs.push(`node-json:${artifacts.nodeRecord.path}`);
+    if (artifacts.decisionEnvelope.exists)
+        refs.push(`decision:${artifacts.decisionEnvelope.path}`);
+    if (artifacts.decisionEnvelopeValidation.exists)
+        refs.push(`decision-validation:${artifacts.decisionEnvelopeValidation.path}`);
+    if (artifacts.humanEscalationJson.exists)
+        refs.push(`escalation-json:${artifacts.humanEscalationJson.path}`);
+    if (artifacts.humanEscalationMd.exists)
+        refs.push(`escalation-md:${artifacts.humanEscalationMd.path}`);
+    if (artifacts.humanApproval.exists)
+        refs.push(`approval:${artifacts.humanApproval.path}`);
+    if (artifacts.humanRejection.exists)
+        refs.push(`rejection:${artifacts.humanRejection.path}`);
+    return refs.length > 0 ? refs.join(", ") : "-";
+}
+function formatCloseoutVerificationEvidence(run) {
+    const verificationNodes = run.nodes.filter((node) => node.executor === "shell" ||
+        node.nodeId.includes("verify") ||
+        node.nodeId.includes("gate"));
+    const targets = verificationNodes.length > 0
+        ? verificationNodes
+        : run.nodes.filter((node) => node.status !== "PENDING");
+    if (targets.length === 0) {
+        return ["No verification evidence nodes found."];
+    }
+    return targets.map((node) => {
+        const artifacts = formatArtifactFlags(node.artifacts);
+        const artifactRefs = formatCloseoutArtifactRefs(node.artifacts);
+        const exitHint = node.failureCategory && node.failureCategory !== "success"
+            ? `exit/failure=${node.failureCategory}`
+            : "exit=0";
+        return `- **${node.nodeId}** (${node.executor}): status=${node.status}, ${exitHint}, normalized=${node.normalizedFailureCategory ?? "-"}, artifacts=${artifacts}, artifactRefs=${artifactRefs}`;
+    });
+}
+function formatCloseoutPrimaryFailureSection(run) {
+    const failure = run.primaryFailure;
+    if (failure.scope === "node" && failure.nodeId) {
+        return [
+            `- **Scope**: node`,
+            `- **Node**: ${failure.nodeId} (${failure.nodeStatus ?? "unknown"})`,
+            `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+        ];
+    }
+    if (run.primaryRecovery.action === "none" &&
+        run.status === "finished" &&
+        !failure.failureCategory) {
+        return ["No primary failure detected."];
+    }
+    return [
+        `- **Scope**: ${failure.scope}`,
+        `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+    ];
+}
+function formatCloseoutRecoverySection(run) {
+    const rec = run.primaryRecovery;
+    return [
+        `- **Action**: \`${rec.action}\``,
+        `- **Summary**: ${rec.summary}`,
+        `- **Reason**: ${rec.reason}`,
+        rec.commandHint ? `- **Command Hint**: ${rec.commandHint}` : undefined,
+    ].filter((line) => line !== undefined);
+}
+function formatSuggestedReportSection(run) {
+    const statusLabel = run.status === "finished" ? "completed successfully" : run.status;
+    return [
+        `- **Title**: ${run.title} (${run.runId})`,
+        `- **Outcome**: Run ${statusLabel} with ${summarizeNodeStatuses(run.nodes)}.`,
+        `- **Primary recovery**: ${run.primaryRecovery.summary} [\`${run.primaryRecovery.action}\`]`,
+        `- **Canonical facts**: \`dag report --run-id ${run.runId} --lifecycle completed --json\``,
+        `- **Run dir**: ${run.runDir}`,
+    ];
+}
+function formatSuggestedProgressSection(run) {
+    return [
+        `- Mark milestone complete for run \`${run.runId}\` (${run.title}).`,
+        `- Status: ${run.status}; lifecycle: ${run.lifecycle}.`,
+        `- Node summary: ${summarizeNodeStatuses(run.nodes)}.`,
+        run.finishedAt
+            ? `- Finished at: ${run.finishedAt}.`
+            : "- Finished at: (not recorded).",
+    ];
+}
+function formatSuggestedHandoffSection(run) {
+    return [
+        `- Next operator action: ${suggestedNextAction(run)}`,
+        `- Review artifacts under \`${run.runDir}\` before publishing docs.`,
+        `- Re-validate with \`dag report --run-id ${run.runId} --lifecycle completed --markdown\`.`,
+    ];
+}
+function formatRemainingRisksSection(run) {
+    const risks = [];
+    if (run.status !== "finished") {
+        risks.push(`- Run status is \`${run.status}\`; confirm recovery before archiving.`);
+    }
+    if (run.primaryRecovery.humanRequired) {
+        risks.push("- Human input is still required per recovery recommendation.");
+    }
+    if (run.downstreamSkippedNodes.length > 0) {
+        risks.push(`- Downstream skipped nodes: ${run.downstreamSkippedNodes.map((node) => node.nodeId).join(", ")}.`);
+    }
+    const failedNodes = failureRows(run);
+    if (failedNodes.length > 0) {
+        risks.push(`- Failed nodes remain in facts: ${failedNodes.map((node) => node.nodeId).join(", ")}.`);
+    }
+    if (risks.length === 0) {
+        risks.push("- No outstanding risks derived from run facts.");
+    }
+    risks.push("- This draft is advisory; edit before committing to `docs/reports/` or `docs/progress/`.");
+    return risks;
+}
+export function formatDagCloseoutDraftMarkdown(run) {
+    const lines = [
+        `# DAG Closeout Draft: ${run.runId}`,
+        "",
+        DAG_CLOSEOUT_DRAFT_DISCLAIMER,
+        "",
+        "## Run Summary",
+        `- **Run ID**: ${run.runId}`,
+        `- **Title**: ${run.title}`,
+        `- **Lifecycle**: ${run.lifecycle}`,
+        `- **Status**: ${run.status}`,
+        `- **Started**: ${formatTimestamp(run.startedAt)}`,
+        `- **Finished**: ${formatTimestamp(run.finishedAt)}`,
+        `- **Duration**: ${formatRunDuration(run.startedAt, run.finishedAt)}`,
+        `- **Nodes**: ${summarizeNodeStatuses(run.nodes)}`,
+        `- **Run Dir**: ${run.runDir}`,
+        "",
+        "## Primary Failure & Recovery",
+        ...formatCloseoutPrimaryFailureSection(run),
+        "",
+        "### Recovery Recommendation",
+        ...formatCloseoutRecoverySection(run),
+        "",
+        "## Node Status Summary",
+        ...formatCloseoutNodeStatusTable(run),
+        "",
+        "## Verification Evidence",
+        ...formatCloseoutVerificationEvidence(run),
+        "",
+        "## Suggested Report Section",
+        ...formatSuggestedReportSection(run),
+        "",
+        "## Suggested Progress Section",
+        ...formatSuggestedProgressSection(run),
+        "",
+        "## Suggested Handoff Section",
+        ...formatSuggestedHandoffSection(run),
+        "",
+        "## Remaining Risks & Next Steps",
+        ...formatRemainingRisksSection(run),
+        "",
+    ];
+    return lines.join("\n");
+}
+export async function buildDagCloseoutDraft(options) {
+    if (options.runId) {
+        const located = await locateDagRun(options.repoRoot, options.runId);
+        if (!located) {
+            throw new Error(`dag run not found: ${options.runId}`);
+        }
+        if (located.lifecycle !== "completed") {
+            throw new Error(`closeout draft requires a completed run; found lifecycle=${located.lifecycle} for run ${options.runId}`);
+        }
+    }
+    const report = await buildDagReport({
+        repoRoot: options.repoRoot,
+        runId: options.runId,
+        lifecycle: "completed",
+        latest: options.runId === undefined,
+    });
+    if (report.runs.length === 0) {
+        if (options.runId) {
+            throw new Error(`dag run not found: ${options.runId}`);
+        }
+        throw new Error("no completed DAG runs found");
+    }
+    const run = report.runs[0];
+    if (run.lifecycle !== "completed") {
+        throw new Error(`closeout draft requires a completed run; found lifecycle=${run.lifecycle} for run ${run.runId}`);
+    }
+    const markdown = formatDagCloseoutDraftMarkdown(run);
+    const outputPath = resolveCloseoutDraftOutputPath(options.repoRoot, options.outputPath ?? defaultCloseoutDraftOutputPath(run.runId));
+    assertCloseoutDraftOutputPathAllowed(options.repoRoot, outputPath);
+    return {
+        run,
+        markdown,
+        outputPath,
+    };
+}