@tea-agent/loop-agent 0.1.0 → 0.2.1

package/dist/workflows/dag/dynamic-runtime/map.js

@@ -0,0 +1,185 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { writeDagRunJsonArtifact } from "../../../infrastructure/harness/artifact-store.js";
+import { executeDagNode, } from "../node-execution.js";
+import { writeRunSpec } from "../run-store.js";
+import { freshNodeRecord, parseJsonFromText, renderDynamicPatternList, renderDynamicTemplate, resolveItemsFromSelector, sha256Json, } from "./shared.js";
+export 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,
+    };
+}
+export 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);
+}
+export function normalizedWritePattern(pattern) {
+    return pattern.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+export 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)));
+}
+export 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;
+}
+export 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;
+}
+export 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 writeRunSpec(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],
+        })),
+    };
+    await writeDagRunJsonArtifact(input.runDir, `expansions/${input.task.id}.expansion.json`, manifest);
+    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,
+            executeDynamicNode: input.executeDynamicNode,
+            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,
+    };
+}

package/dist/workflows/dag/dynamic-runtime/reduction.js

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { writeDagNodeJsonArtifact } from "../../../infrastructure/harness/artifact-store.js";
+import { repoRelativePath, toPosixPath } from "../../../shared/path-refs.js";
+import { buildVerifiedFindingsReport, findingSchema, verificationSchema, } from "../../dynamic/artifacts.js";
+import { parseJsonFromText, resolveOutputSelector } from "./shared.js";
+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));
+}
+export 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);
+    const refutedFindingsPath = path.join(nodeDir, input.reduction.refutedFindingsArtifactName);
+    const { report, refutedFindings } = buildVerifiedFindingsReport({
+        findings,
+        verifications,
+        refutedFindingsRef: refutedFindingsPath.startsWith(input.runDir)
+            ? repoRelativePath(input.runDir, refutedFindingsPath)
+            : toPosixPath(refutedFindingsPath),
+    });
+    await writeDagNodeJsonArtifact(input.runDir, input.task.id, input.reduction.refutedFindingsArtifactName, refutedFindings);
+    return {
+        ok: true,
+        stdout: JSON.stringify(report),
+        stderr: "",
+        failureCategory: "success",
+        durationMs: Date.now() - started,
+    };
+}

package/dist/workflows/dag/dynamic-runtime/shared.js

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+export function freshNodeRecord(task) {
+    return {
+        id: task.id,
+        status: "PENDING",
+        executor: task.executor,
+        complexity: task.complexity,
+    };
+}
+export function sha256Json(value) {
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify(value))
+        .digest("hex")}`;
+}
+export 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)}`);
+    }
+}
+export 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;
+}
+export 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;
+}
+export 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;
+}
+export 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);
+}
+export 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;
+}
+export function parseJsonFromText(value) {
+    if (!value?.trim())
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+export 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));
+}
+export function renderDynamicPatternList(patterns, item, index, itemName) {
+    return patterns?.map((pattern) => renderDynamicTemplate(pattern, item, index, itemName));
+}

package/dist/workflows/dag/failure-routing.js

@@ -0,0 +1,82 @@
+export const dagProductLineFailureCategoryValues = [
+    "SpecUnclear",
+    "ContractMismatch",
+    "ProductBug",
+    "TestBug",
+    "EnvFailure",
+    "FlakyTest",
+    "RiskyChange",
+    "DependencyFailure",
+    "NeedsHuman",
+    "Unknown",
+];
+const FOLLOW_UP_BY_PRODUCT_LINE = {
+    SpecUnclear: "spec-clarification",
+    ContractMismatch: "architecture-contract-fix",
+    ProductBug: "dev-fix",
+    TestBug: "qa-fix-test",
+    EnvFailure: "env-fix or retry verify",
+    FlakyTest: "flaky-test-analysis",
+    RiskyChange: "human-review or architecture-review",
+    DependencyFailure: "unblock dependency",
+    NeedsHuman: "human-review",
+    Unknown: "human triage",
+};
+function routeToProductLine(input) {
+    const normalized = input.normalizedFailureCategory;
+    if (!normalized || normalized === "success")
+        return undefined;
+    const raw = input.rawFailureCategory?.toLowerCase() ?? "";
+    const nodeId = input.nodeId?.toLowerCase() ?? "";
+    switch (normalized) {
+        case "write-guard":
+            return "RiskyChange";
+        case "auth":
+        case "executor":
+        case "timeout":
+            return "EnvFailure";
+        case "human-required":
+        case "human-rejected":
+        case "decision-envelope":
+            return "NeedsHuman";
+        case "skipped":
+            return "DependencyFailure";
+        case "shell-command":
+            if (raw.includes("flaky"))
+                return "FlakyTest";
+            if (nodeId.includes("test") || raw.includes("test-bug")) {
+                return "TestBug";
+            }
+            return "ProductBug";
+        case "static-error":
+            return "SpecUnclear";
+        case "validation":
+            if (raw.includes("path") ||
+                raw.includes("write") ||
+                raw.includes("forbidden")) {
+                return "RiskyChange";
+            }
+            if (raw.includes("test-bug") || nodeId.includes("test")) {
+                return "TestBug";
+            }
+            if (raw.includes("test-failure") || raw.includes("verify-failure")) {
+                return "ProductBug";
+            }
+            return "SpecUnclear";
+        case "unknown":
+            return "Unknown";
+        default: {
+            const exhaustive = normalized;
+            return exhaustive;
+        }
+    }
+}
+export function routeDagFailure(input) {
+    const productLineFailureCategory = routeToProductLine(input);
+    if (!productLineFailureCategory)
+        return {};
+    return {
+        productLineFailureCategory,
+        recommendedFollowUp: FOLLOW_UP_BY_PRODUCT_LINE[productLineFailureCategory],
+    };
+}

package/dist/workflows/dag/lifecycle.js

@@ -1,6 +1,9 @@
-import { access, mkdir, readFile, readdir, rename, writeFile, } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rename, } from "node:fs/promises";
 import path from "node:path";
+import { writeJsonAtomic, } from "../../infrastructure/harness/atomic-write.js";
 import { parseDagSpec } from "./types.js";
+import { normalizeDagFailureCategory, } from "./failure-category.js";
+import { routeDagFailure } from "./failure-routing.js";
 const DAG_LIFECYCLE_SCAN_ORDER = [
     "paused",
     "active",
@@ -24,8 +27,8 @@ export async function readDagRunState(runDir) {
     const raw = JSON.parse(await readFile(path.join(runDir, "state.json"), "utf-8"));
     return raw;
 }
-export async function writeDagRunState(runDir, state) {
-    await writeFile(path.join(runDir, "state.json"), `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+export async function writeDagRunState(runDir, state, options) {
+    await writeJsonAtomic(path.join(runDir, "state.json"), state, options);
 }
 export async function readDagRunSpec(runDir) {
     const raw = JSON.parse(await readFile(path.join(runDir, "run.json"), "utf-8"));
@@ -131,14 +134,14 @@ export async function writeHumanApprovalArtifact(input) {
     const nodeDir = path.join(input.runDir, input.nodeId);
     await mkdir(nodeDir, { recursive: true });
     const artifactPath = path.join(nodeDir, "human-approval.json");
-    await writeFile(artifactPath, `${JSON.stringify(input.artifact, null, 2)}\n`, "utf-8");
+    await writeJsonAtomic(artifactPath, input.artifact);
     return artifactPath;
 }
 export async function writeHumanRejectionArtifact(input) {
     const nodeDir = path.join(input.runDir, input.nodeId);
     await mkdir(nodeDir, { recursive: true });
     const artifactPath = path.join(nodeDir, "human-rejection.json");
-    await writeFile(artifactPath, `${JSON.stringify(input.artifact, null, 2)}\n`, "utf-8");
+    await writeJsonAtomic(artifactPath, input.artifact);
     return artifactPath;
 }
 export async function readHumanApprovalArtifact(runDir, nodeId) {
@@ -469,16 +472,106 @@ export async function runDagStatus(repoRoot, rawArgs) {
     console.log(JSON.stringify(report, null, 2));
 }
 export function parseDagDoctorArgs(args) {
-    for (const arg of args) {
+    let runId;
+    let markdown = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--run-id") {
+            runId = args[++i];
+            if (!runId || runId.startsWith("-")) {
+                throw new Error("dag doctor --run-id requires a value");
+            }
+            continue;
+        }
+        if (arg.startsWith("--run-id=")) {
+            runId = arg.slice("--run-id=".length);
+            if (!runId)
+                throw new Error("dag doctor --run-id requires a value");
+            continue;
+        }
+        if (arg === "--markdown") {
+            markdown = true;
+            continue;
+        }
         if (arg.startsWith("-")) {
             throw new Error(`unknown dag doctor flag: ${arg}`);
         }
         throw new Error(`unexpected positional argument: ${arg}`);
     }
-    return {};
+    return { runId, markdown };
+}
+function findDoctorFailureNode(state) {
+    if (state.pausedByNodeId) {
+        const node = state.nodes[state.pausedByNodeId];
+        return {
+            nodeId: state.pausedByNodeId,
+            status: node?.status,
+            rawFailureCategory: node?.failureCategory,
+        };
+    }
+    const errorEntry = Object.entries(state.nodes).find(([, node]) => node.status === "ERROR");
+    const skippedEntry = Object.entries(state.nodes).find(([, node]) => node.status === "SKIPPED");
+    const selected = errorEntry ?? skippedEntry;
+    if (!selected) {
+        return {
+            rawFailureCategory: state.failureCategory,
+            status: state.status,
+        };
+    }
+    return {
+        nodeId: selected[0],
+        status: selected[1].status,
+        rawFailureCategory: selected[1].failureCategory,
+    };
+}
+async function formatDagDoctorMarkdown(repoRoot, runId) {
+    const located = await locateDagRun(repoRoot, runId);
+    if (!located) {
+        throw new Error(`dag run not found: ${runId}`);
+    }
+    const state = await readDagRunState(located.runDir);
+    const summary = await buildDagStatusReport(repoRoot, runId);
+    const failure = findDoctorFailureNode(state);
+    const rawFailureCategory = failure.rawFailureCategory ??
+        (state.status === "paused" ? "human-required" : state.failureCategory);
+    const failureStatus = state.status === "paused" ? "paused" : failure.status;
+    const normalizedCategory = normalizeDagFailureCategory(rawFailureCategory, failureStatus ?? state.status);
+    const routing = routeDagFailure({
+        rawFailureCategory,
+        normalizedFailureCategory: normalizedCategory,
+        nodeId: failure.nodeId,
+    });
+    const evidence = failure.nodeId
+        ? path.join(located.runDir, failure.nodeId, "result.summary.md")
+        : path.join(located.runDir, "state.json");
+    const nextCommand = summary.nextRecommendedAction ||
+        routing.recommendedFollowUp ||
+        "Inspect run facts and choose a recovery path.";
+    return [
+        "## Diagnosis",
+        "",
+        `- run id: ${runId}`,
+        `- lifecycle: ${located.lifecycle}`,
+        `- failed node: ${failure.nodeId ?? "-"}`,
+        `- raw failure: ${rawFailureCategory ?? "-"}`,
+        `- normalized category: ${normalizedCategory}`,
+        `- product-line category: ${routing.productLineFailureCategory ?? "-"}`,
+        `- recommended follow-up: ${routing.recommendedFollowUp ?? "-"}`,
+        `- evidence: ${evidence}`,
+        `- next command: ${nextCommand}`,
+        "",
+    ].join("\n");
 }
 export async function runDagDoctor(repoRoot, rawArgs) {
-    parseDagDoctorArgs(rawArgs);
+    const parsed = parseDagDoctorArgs(rawArgs);
+    if (parsed.runId) {
+        if (parsed.markdown) {
+            console.log(await formatDagDoctorMarkdown(repoRoot, parsed.runId));
+            return;
+        }
+        console.log(JSON.stringify(await buildDagStatusReport(repoRoot, parsed.runId), null, 2));
+        return;
+    }
     const report = await buildDagDoctorReport(repoRoot);
     console.log(JSON.stringify(report, null, 2));
 }