@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0-beta.0

package/bin/agent-worker.js

@@ -1,22 +1,22 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const cliEntry = join(packageRoot, "dist", "worker", "cli.js");
-
-if (!existsSync(cliEntry)) {
-  console.error(
-    `agent-worker: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
-  );
-  process.exit(1);
-}
-
-try {
-  const cli = await import(pathToFileURL(cliEntry).href);
-  await cli.main(process.argv);
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const cliEntry = join(packageRoot, "dist", "worker", "cli.js");
+
+if (!existsSync(cliEntry)) {
+  console.error(
+    `agent-worker: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
+  );
+  process.exit(1);
+}
+
+try {
+  const cli = await import(pathToFileURL(cliEntry).href);
+  await cli.main(process.argv);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/bin/loop-agent.js

@@ -1,21 +1,21 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const cliEntry = join(packageRoot, "dist", "cli.js");
-
-if (!existsSync(cliEntry)) {
-  console.error(
-    `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
-  );
-  process.exit(1);
-}
-
-try {
-  await import(pathToFileURL(cliEntry).href);
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const cliEntry = join(packageRoot, "dist", "cli.js");
+
+if (!existsSync(cliEntry)) {
+  console.error(
+    `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
+  );
+  process.exit(1);
+}
+
+try {
+  await import(pathToFileURL(cliEntry).href);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/application/dag/generate-task-dag.js

@@ -1,4 +1,6 @@
-import { readFile } from "node:fs/promises";
+import { readFile, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
 import { resolveAutoRoutingProfile, requiresSupervisedQualityGate, } from "../../workflows/dag/governance-profile.js";
 import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { parseDagSpec } from "../../workflows/dag/types.js";
@@ -6,7 +8,6 @@ import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
 import { assertExecPlanIndexConsistent } from "../../governance/exec-plans.js";
 import { defaultHybridDagOutputPath, initHybridDagFromTask, } from "../../workflows/dag/init-hybrid.js";
-import { loadTaskConfig } from "../../task/runtime.js";
 import { validateDagUseCase } from "./validate-dag.js";
 import { runDagUseCase } from "./run-dag.js";
 const PLACEHOLDER_WRITESET_MARKER = "REPLACE/WITH";
@@ -202,11 +203,6 @@ export async function generateTaskDagUseCase(input) {
     // before any expensive DAG generation or execution. Empty/consistent
     // repos stay compatible so the default DAG flow is unblocked.
     await assertExecPlanIndexConsistent(repoRoot);
-    const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
-    const isFrontendImplementationTask = taskConfig.taskKind === "frontend-implementation";
-    const isBackendTestTask = taskConfig.taskKind === "backend-test";
-    const isKnowledgeSyncTask = taskConfig.taskKind === "knowledge-sync";
-    const isKnowledgeGraphBootstrapTask = taskConfig.taskKind === "knowledge-graph-bootstrap";
     const candidateResult = await initHybridDagFromTask(repoRoot, parsed.taskId, {
         outputPath: parsed.outputPath,
         template: "standard-dag",
@@ -219,12 +215,16 @@ export async function generateTaskDagUseCase(input) {
         codeChange: [],
         reasons: ["dag run-task validate did not report governanceProfile"],
     });
-    if (isFrontendImplementationTask) {
-        profileRouting.selectedTemplate = "frontend-implementation";
-        profileRouting.source = "taskKind";
-        profileRouting.routingReasons = [
-            'taskKind "frontend-implementation" selects the dedicated frontend DAG template',
-        ];
+    const hasExplicitSpecializedTaskKind = candidateResult.templateSelection.source === "taskKind";
+    const hasSafeAutomaticTaskSourceRoute = candidateResult.templateSelection.source === "task-source" &&
+        profileRouting.selectedByProfile !== "supervised" &&
+        profileRouting.selectedTemplate !== "supervised-implementation";
+    if (hasExplicitSpecializedTaskKind || hasSafeAutomaticTaskSourceRoute) {
+        profileRouting.selectedTemplate = candidateResult.template;
+        profileRouting.source = hasExplicitSpecializedTaskKind
+            ? "taskKind"
+            : "task-source";
+        profileRouting.routingReasons = candidateResult.templateSelection.reasons;
         if (parsed.profile === "auto") {
             profileRouting.selectedByProfile =
                 resolveAutoRoutingProfile(profileRouting.candidateProfile);
@@ -233,56 +233,14 @@ export async function generateTaskDagUseCase(input) {
             profileRouting.selectedByProfile = parsed.profile;
         }
     }
-    if (isBackendTestTask) {
-        profileRouting.selectedTemplate = "backend-test-dag";
-        profileRouting.source = "taskKind";
-        profileRouting.routingReasons = [
-            'taskKind "backend-test" selects the dedicated backend test DAG template',
-        ];
-        if (parsed.profile === "auto") {
-            profileRouting.selectedByProfile =
-                resolveAutoRoutingProfile(profileRouting.candidateProfile);
-        }
-        else if (parsed.profileExplicit) {
-            profileRouting.selectedByProfile = parsed.profile;
-        }
-    }
-    if (isKnowledgeSyncTask) {
-        profileRouting.selectedTemplate = "knowledge-sync-dag";
-        profileRouting.source = "taskKind";
-        profileRouting.routingReasons = [
-            'taskKind "knowledge-sync" selects the dedicated knowledge-sync DAG template',
-        ];
-        if (parsed.profile === "auto") {
-            profileRouting.selectedByProfile =
-                resolveAutoRoutingProfile(profileRouting.candidateProfile);
-        }
-        else if (parsed.profileExplicit) {
-            profileRouting.selectedByProfile = parsed.profile;
-        }
-    }
-    if (isKnowledgeGraphBootstrapTask) {
-        profileRouting.selectedTemplate = "knowledge-graph-bootstrap-dag";
-        profileRouting.source = "taskKind";
-        profileRouting.routingReasons = [
-            'taskKind "knowledge-graph-bootstrap" selects the dedicated knowledge-graph bootstrap DAG template',
-        ];
-        if (parsed.profile === "auto") {
-            profileRouting.selectedByProfile =
-                resolveAutoRoutingProfile(profileRouting.candidateProfile);
-        }
-        else if (parsed.profileExplicit) {
-            profileRouting.selectedByProfile = parsed.profile;
-        }
-    }
-    const initResult = profileRouting.selectedTemplate === "standard-dag"
+    const initResult = profileRouting.selectedTemplate === candidateResult.template
         ? candidateResult
         : await initHybridDagFromTask(repoRoot, parsed.taskId, {
             outputPath: parsed.outputPath,
             template: profileRouting.selectedTemplate,
         });
     const outputPath = initResult.outputPath;
-    const validateSummary = profileRouting.selectedTemplate === "standard-dag"
+    const validateSummary = profileRouting.selectedTemplate === candidateResult.template
         ? candidateValidateSummary
         : await validateDagUseCase(buildValidateInput(repoRoot, outputPath, parsed));
     const governanceProfile = validateSummary.governanceProfile ?? {
@@ -317,6 +275,17 @@ export async function generateTaskDagUseCase(input) {
         };
     }
     await assertSafeForExecution(outputPath);
+    // Mirror worker run-task layout so Observe can find dag-events.jsonl under
+    // .harness/task-pool/observability/runs/<runId>/ (CLI path, not Task Pool state).
+    const runId = parsed.runId ?? `dag-${Date.now()}-${randomUUID().slice(0, 8)}`;
+    const eventsJsonlPath = path.join(parsed.cwd, ".harness", "task-pool", "observability", "runs", runId, "dag-events.jsonl");
+    try {
+        await mkdir(path.dirname(eventsJsonlPath), { recursive: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to create dag events directory for observe: ${path.dirname(eventsJsonlPath)}: ${message}`);
+    }
     const runSummary = await runDagUseCase({
         repoRoot,
         dagPath: outputPath,
@@ -324,7 +293,8 @@ export async function generateTaskDagUseCase(input) {
         initOnly: parsed.initOnly,
         dryRun: parsed.dryRun,
         maxConcurrent: parsed.maxConcurrent,
-        runId: parsed.runId,
+        runId,
+        eventsJsonlPath,
         canvasPath: parsed.canvasPath,
         canvasName: parsed.canvasName,
         canvasesDir: parsed.canvasesDir,

package/dist/application/evaluation/candidate-hash.js

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+/** Deterministic JSON stringify: object keys sorted at every level. */
+export function stableStringify(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalize(item));
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const out = {};
+    for (const key of keys) {
+        out[key] = canonicalize(obj[key]);
+    }
+    return out;
+}
+export function normalizeContentSha(value) {
+    const trimmed = value.trim();
+    const bare = trimmed.startsWith("sha256:")
+        ? trimmed.slice("sha256:".length)
+        : trimmed;
+    if (!/^[a-f0-9]{64}$/i.test(bare)) {
+        throw new Error(`invalid content sha256: ${value}`);
+    }
+    return bare.toLowerCase();
+}
+export function formatContentSha(hex) {
+    return `sha256:${normalizeContentSha(hex)}`;
+}
+export function normalizeContentRefs(refs) {
+    const normalized = refs.map((ref) => ({
+        path: ref.path.replace(/\\/g, "/"),
+        sha256: normalizeContentSha(ref.sha256),
+    }));
+    normalized.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const seen = new Set();
+    for (const ref of normalized) {
+        if (seen.has(ref.path)) {
+            throw new Error(`duplicate content ref path: ${ref.path}`);
+        }
+        seen.add(ref.path);
+    }
+    return normalized;
+}
+/**
+ * Canonical payload for bundleHash.
+ * Excludes candidateId, createdAt, description, bundleHash, absolute paths,
+ * registry location, and any mutable lifecycle state.
+ */
+export function buildCanonicalBundlePayload(manifest) {
+    return {
+        schemaVersion: 1,
+        candidateKind: manifest.candidateKind,
+        parentCandidateId: manifest.parentCandidateId ?? null,
+        contentRefs: normalizeContentRefs(manifest.contentRefs),
+    };
+}
+export function computeBundleHash(manifest) {
+    const payload = buildCanonicalBundlePayload(manifest);
+    const digest = createHash("sha256")
+        .update(stableStringify(payload))
+        .digest("hex");
+    return formatContentSha(digest);
+}
+export function sha256Hex(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function eventHashHex(payload) {
+    return createHash("sha256").update(stableStringify(payload)).digest("hex");
+}
+export const LIFECYCLE_GENESIS_HASH = "0".repeat(64);

package/dist/application/evaluation/candidate.js

@@ -0,0 +1,52 @@
+import { loadManifestInputFromPath, listCandidateIds, materializeManifest, readCandidateRecord, registerCandidateManifest, transitionCandidateLifecycle, } from "../../infrastructure/evaluation/candidate-store.js";
+export async function registerCandidate(input) {
+    const raw = await loadManifestInputFromPath(input.repoRoot, input.manifestPath);
+    const manifest = await materializeManifest(input.repoRoot, raw);
+    return registerCandidateManifest({
+        repoRoot: input.repoRoot,
+        manifest,
+        now: input.now,
+    });
+}
+export async function showCandidate(input) {
+    return readCandidateRecord(input.repoRoot, input.candidateId);
+}
+export async function listCandidates(input) {
+    const ids = await listCandidateIds(input.repoRoot);
+    const rows = [];
+    for (const candidateId of ids) {
+        const record = await readCandidateRecord(input.repoRoot, candidateId);
+        rows.push({
+            candidateId: record.manifest.candidateId,
+            bundleHash: record.manifest.bundleHash,
+            candidateKind: record.manifest.candidateKind,
+            status: record.status,
+            promotionApplied: false,
+        });
+    }
+    return rows;
+}
+export async function transitionCandidate(input) {
+    return transitionCandidateLifecycle(input);
+}
+export function formatCandidateMarkdown(record) {
+    const lines = [
+        `# Candidate: ${record.manifest.candidateId}`,
+        "",
+        `- status: \`${record.status}\``,
+        `- kind: \`${record.manifest.candidateKind}\``,
+        `- bundleHash: \`${record.manifest.bundleHash}\``,
+        `- parent: \`${record.manifest.parentCandidateId ?? "null"}\``,
+        `- promotionApplied: \`false\` (registry lifecycle only; no alias/incumbent)`,
+        "",
+        "## Content refs",
+        "",
+        ...record.manifest.contentRefs.map((ref) => `- \`${ref.path}\` — \`${ref.sha256}\``),
+        "",
+        "## Lifecycle",
+        "",
+        ...record.events.map((event) => `- #${event.seq} ${event.from ?? "∅"} → ${event.to}: ${event.reason} (${event.at})`),
+        "",
+    ];
+    return `${lines.join("\n")}\n`;
+}

package/dist/application/evaluation/replay.js

@@ -0,0 +1,289 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { reportDagUseCase } from "../dag/report-dag.js";
+import { readReplaySpec, writeReplayArtifacts, } from "../../infrastructure/evaluation/store.js";
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function pairKey(input) {
+    return `${input.split}\u0000${input.taskRef}\u0000${input.seed}`;
+}
+async function verifyEvidenceHash(input) {
+    const content = await readFile(input.filePath);
+    const actual = sha256(content);
+    if (actual !== input.expected) {
+        throw new Error(`${input.label} hash mismatch: expected ${input.expected}, got ${actual}`);
+    }
+}
+function sumOptional(values) {
+    if (values.some((value) => value === undefined)) {
+        return { value: null, missing: true };
+    }
+    return {
+        value: values.reduce((sum, value) => sum + (value ?? 0), 0),
+        missing: false,
+    };
+}
+function verifyPassed(input) {
+    if (input.status !== "finished")
+        return false;
+    const verificationNodes = input.nodes.filter((node) => node.executor === "shell" ||
+        node.nodeId.includes("verify") ||
+        node.nodeId.includes("gate"));
+    return (verificationNodes.length > 0 &&
+        verificationNodes.every((node) => node.status === "FINISHED" &&
+            (!node.failureCategory || node.failureCategory === "success")));
+}
+function metricsForRun(run) {
+    const tokens = sumOptional(run.nodes.map((node) => node.tokensUsed));
+    const duration = sumOptional(run.nodes.map((node) => node.durationMs));
+    const missingFields = [];
+    if (tokens.missing)
+        missingFields.push("tokens");
+    if (duration.missing)
+        missingFields.push("durationMs");
+    return {
+        metrics: {
+            verifyPassed: verifyPassed(run),
+            tokens: tokens.value,
+            durationMs: duration.value,
+            executorCalls: run.nodes.length,
+            repairPasses: run.convergence?.currentPass ?? 0,
+        },
+        missingFields,
+    };
+}
+function compareRows(incumbent, challenger) {
+    const reasons = [];
+    let verdict;
+    if (incumbent.metrics.verifyPassed !== challenger.metrics.verifyPassed) {
+        verdict = challenger.metrics.verifyPassed
+            ? "challenger_win"
+            : "incumbent_win";
+        reasons.push("verification_outcome");
+    }
+    else if (!incumbent.metrics.verifyPassed) {
+        verdict = "tie";
+        reasons.push("both_failed_verification");
+    }
+    else if (incumbent.metrics.tokens === null ||
+        challenger.metrics.tokens === null ||
+        incumbent.metrics.durationMs === null ||
+        challenger.metrics.durationMs === null) {
+        verdict = "incomparable";
+        reasons.push("missing_cost_metrics");
+    }
+    else {
+        const challengerNoWorse = challenger.metrics.tokens <= incumbent.metrics.tokens &&
+            challenger.metrics.durationMs <= incumbent.metrics.durationMs;
+        const incumbentNoWorse = incumbent.metrics.tokens <= challenger.metrics.tokens &&
+            incumbent.metrics.durationMs <= challenger.metrics.durationMs;
+        if (challengerNoWorse && !incumbentNoWorse) {
+            verdict = "challenger_win";
+            reasons.push("lower_cost");
+        }
+        else if (incumbentNoWorse && !challengerNoWorse) {
+            verdict = "incumbent_win";
+            reasons.push("lower_cost");
+        }
+        else if (challengerNoWorse && incumbentNoWorse) {
+            verdict = "tie";
+            reasons.push("equal_metrics");
+        }
+        else {
+            verdict = "incomparable";
+            reasons.push("cost_tradeoff");
+        }
+    }
+    return {
+        taskRef: incumbent.taskRef,
+        seed: incumbent.seed,
+        split: incumbent.split,
+        incumbentRunId: incumbent.runId,
+        challengerRunId: challenger.runId,
+        verdict,
+        reasons,
+    };
+}
+function buildScorecard(input) {
+    const rows = [...input.rows].sort((left, right) => [
+        left.split,
+        left.taskRef,
+        String(left.seed).padStart(12, "0"),
+        left.candidateId,
+        left.runId,
+    ]
+        .join("\u0000")
+        .localeCompare([
+        right.split,
+        right.taskRef,
+        String(right.seed).padStart(12, "0"),
+        right.candidateId,
+        right.runId,
+    ].join("\u0000")));
+    const incumbentByKey = new Map(rows
+        .filter((row) => row.candidateId === input.incumbentCandidateId)
+        .map((row) => [pairKey(row), row]));
+    const challengerByKey = new Map(rows
+        .filter((row) => row.candidateId === input.challengerCandidateId)
+        .map((row) => [pairKey(row), row]));
+    const keys = [
+        ...new Set([...incumbentByKey.keys(), ...challengerByKey.keys()]),
+    ].sort();
+    const comparisons = [];
+    let unpairedEvidenceCount = 0;
+    for (const key of keys) {
+        const incumbent = incumbentByKey.get(key);
+        const challenger = challengerByKey.get(key);
+        if (!incumbent || !challenger) {
+            unpairedEvidenceCount +=
+                Number(Boolean(incumbent)) + Number(Boolean(challenger));
+            continue;
+        }
+        comparisons.push(compareRows(incumbent, challenger));
+    }
+    const reasons = ["replay_only"];
+    if (comparisons.length === 0)
+        reasons.push("insufficient_samples");
+    if (unpairedEvidenceCount > 0)
+        reasons.push("unpaired_evidence");
+    return {
+        schemaVersion: 1,
+        replayId: input.replayId,
+        incumbentCandidateId: input.incumbentCandidateId,
+        challengerCandidateId: input.challengerCandidateId,
+        rows,
+        comparisons,
+        aggregate: {
+            pairedSampleCount: comparisons.length,
+            incumbentWins: comparisons.filter((item) => item.verdict === "incumbent_win").length,
+            challengerWins: comparisons.filter((item) => item.verdict === "challenger_win").length,
+            ties: comparisons.filter((item) => item.verdict === "tie").length,
+            incomparable: comparisons.filter((item) => item.verdict === "incomparable").length,
+            unpairedEvidenceCount,
+            promotionEligible: false,
+            reasons,
+        },
+    };
+}
+export function formatReplayMarkdown(scorecard) {
+    const lines = [
+        `# Eval Replay Scorecard: ${scorecard.replayId}`,
+        "",
+        "> Replay-only evidence. This report never authorizes promotion or executes Pi/DAG work.",
+        "",
+        `- incumbent: ${scorecard.incumbentCandidateId}`,
+        `- challenger: ${scorecard.challengerCandidateId}`,
+        `- promotionEligible: ${scorecard.aggregate.promotionEligible}`,
+        `- reasons: ${scorecard.aggregate.reasons.join(", ")}`,
+        "",
+        "## Evidence",
+        "",
+        "| split | task | seed | candidate | run | verified | tokens | durationMs | calls | repairPasses | missing |",
+        "|---|---|---:|---|---|---|---:|---:|---:|---:|---|",
+    ];
+    for (const row of scorecard.rows) {
+        lines.push(`| ${row.split} | ${row.taskRef} | ${row.seed} | ${row.candidateId} | ${row.runId} | ${row.metrics.verifyPassed} | ${row.metrics.tokens ?? "n/a"} | ${row.metrics.durationMs ?? "n/a"} | ${row.metrics.executorCalls} | ${row.metrics.repairPasses} | ${row.missingFields.join(", ") || "none"} |`);
+    }
+    lines.push("", "## Paired Comparisons", "", "| split | task | seed | incumbent run | challenger run | verdict | reasons |", "|---|---|---:|---|---|---|---|");
+    for (const comparison of scorecard.comparisons) {
+        lines.push(`| ${comparison.split} | ${comparison.taskRef} | ${comparison.seed} | ${comparison.incumbentRunId} | ${comparison.challengerRunId} | ${comparison.verdict} | ${comparison.reasons.join(", ")} |`);
+    }
+    if (scorecard.comparisons.length === 0) {
+        lines.push("| - | - | - | - | - | - | no paired evidence |");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function replayEvaluation(input) {
+    const spec = await readReplaySpec(input.repoRoot, input.specPath);
+    const rows = [];
+    for (const evidence of spec.evidence) {
+        const runDir = path.join(input.repoRoot, ".harness", "dag-runs", "completed", evidence.runId);
+        const statePath = path.join(runDir, "state.json");
+        const runPath = path.join(runDir, "run.json");
+        const stateRefPath = path
+            .relative(input.repoRoot, statePath)
+            .split(path.sep)
+            .join("/");
+        const runRefPath = path
+            .relative(input.repoRoot, runPath)
+            .split(path.sep)
+            .join("/");
+        await verifyEvidenceHash({
+            filePath: statePath,
+            expected: evidence.stateSha256,
+            label: "state.json",
+        });
+        await verifyEvidenceHash({
+            filePath: runPath,
+            expected: evidence.runSha256,
+            label: "run.json",
+        });
+        const report = await reportDagUseCase({
+            repoRoot: input.repoRoot,
+            runId: evidence.runId,
+            lifecycle: "completed",
+            failedOnly: false,
+            latest: false,
+        });
+        const run = report.runs[0];
+        if (!run) {
+            throw new Error(`completed DAG run not found: ${evidence.runId}`);
+        }
+        if (run.evaluationAssociation.status === "present") {
+            if (run.evaluationAssociation.candidateId !== evidence.candidateId) {
+                throw new Error(`replay evidence candidateId conflict for ${evidence.runId}: evidence=${evidence.candidateId}, run=${run.evaluationAssociation.candidateId}`);
+            }
+            if (run.evaluationAssociation.seed !== evidence.seed) {
+                throw new Error(`replay evidence seed conflict for ${evidence.runId}: evidence=${evidence.seed}, run=${run.evaluationAssociation.seed}`);
+            }
+            if (run.evaluationAssociation.split &&
+                run.evaluationAssociation.split !== evidence.split) {
+                throw new Error(`replay evidence split conflict for ${evidence.runId}: evidence=${evidence.split}, run=${run.evaluationAssociation.split}`);
+            }
+            if (run.evaluationAssociation.taskRef &&
+                run.evaluationAssociation.taskRef !== evidence.taskRef) {
+                throw new Error(`replay evidence taskRef conflict for ${evidence.runId}: evidence=${evidence.taskRef}, run=${run.evaluationAssociation.taskRef}`);
+            }
+        }
+        if (![
+            "finished",
+            "failed",
+            "partial_failed",
+            "superseded",
+            "abandoned",
+        ].includes(run.status)) {
+            throw new Error(`completed DAG run ${evidence.runId} is not terminal (status=${run.status})`);
+        }
+        const { metrics, missingFields } = metricsForRun(run);
+        rows.push({
+            ...evidence,
+            lifecycle: "completed",
+            runStatus: run.status,
+            metrics,
+            missingFields,
+            evidenceRefs: [
+                { path: stateRefPath, sha256: evidence.stateSha256 },
+                { path: runRefPath, sha256: evidence.runSha256 },
+            ],
+        });
+    }
+    const scorecard = buildScorecard({
+        replayId: spec.replayId,
+        incumbentCandidateId: spec.incumbentCandidateId,
+        challengerCandidateId: spec.challengerCandidateId,
+        rows,
+    });
+    const markdown = formatReplayMarkdown(scorecard);
+    if (input.writeArtifacts === false) {
+        return { scorecard, markdown };
+    }
+    const paths = await writeReplayArtifacts({
+        repoRoot: input.repoRoot,
+        replayId: spec.replayId,
+        scorecard,
+        markdown,
+    });
+    return { scorecard, markdown, ...paths };
+}