@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/workflows/dag/prompt.js

@@ -0,0 +1,348 @@
+import { DEFAULT_DAG_OUTPUT_LANGUAGE, } from "./types.js";
+import { formatStdoutPreview, formatUpstreamArtifactPointerMap, } from "./upstream-artifacts.js";
+export const MAX_UPSTREAM_CHARS = 2_000;
+/** Shared bullets for DAG authoring templates, docs, and planner-node envelopes. */
+export const DAG_AUTHORING_GUIDANCE = [
+    "Prefer same-rank parallel read-only scouts over unnecessary serial depends_on chains.",
+    "Add depends_on only when a child truly needs upstream output; default to independent ranks.",
+    "Every task must explicitly declare executor; defaults.executor is schema-only, not a runtime fallback.",
+    "Pi is the only governed Agent DAG writer; cursor-prompt is an explicit manual one-shot sidecar and must not enter Loop auto-execute or Delegate writers.",
+    "exclusive nodes require narrow, concrete, disjoint writeSet paths; never use ** or repo root.",
+    "Read-only nodes must not write repository files, including root artifacts/**; return findings in node output only.",
+    "If the DAG is a single linear chain, challenge whether read-only work can run in parallel ranks.",
+];
+const PLANNER_AUTHORING_ROLES = new Set(["planner"]);
+function formatBulletList(items, emptyLabel) {
+    if (!items || items.length === 0)
+        return emptyLabel;
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function formatPaths(paths) {
+    if (!paths || paths.length === 0)
+        return "(none)";
+    return paths.join(", ");
+}
+function resolveWritePolicy(task, spec) {
+    return task.writePolicy ?? spec.defaults?.writePolicy ?? "(not specified)";
+}
+function resolveOutputContract(task) {
+    return task.outputContract ?? "(none)";
+}
+function formatAuthoringGuidanceBlock() {
+    return DAG_AUTHORING_GUIDANCE.map((item) => `- ${item}`).join("\n");
+}
+function formatExecutor(task) {
+    return (task.executor ??
+        "(not specified — declare executor explicitly on every task)");
+}
+function formatResolvedSkillInstructions(instructions) {
+    if (!instructions || instructions.length === 0)
+        return "(none)";
+    return instructions
+        .map((instruction) => instruction.promptText)
+        .join("\n\n---\n\n");
+}
+export function formatOutputLanguageBlock(language = DEFAULT_DAG_OUTPUT_LANGUAGE) {
+    if (language === "en") {
+        return [
+            "Write prose, analysis, reports, summaries, and documentation in English.",
+            "Keep code, commands, paths, identifiers, JSON keys, exact protocol tokens, verdict lines, and output-contract literals unchanged.",
+            "If the node task explicitly requires another language, follow the explicit task requirement.",
+        ].join("\n");
+    }
+    return [
+        "使用简体中文撰写说明、分析、报告、总结和文档正文。",
+        "代码、命令、路径、标识符、JSON 字段、精确协议 token、VERDICT 行以及 output contract 中要求的字面量保持原样，不要翻译。",
+        "如果当前节点任务明确要求其他语言，以节点的明确要求为准。",
+    ].join("\n");
+}
+export function buildUpstreamContext(task, upstream, maxChars = MAX_UPSTREAM_CHARS) {
+    const sections = [];
+    const toleratedFailures = new Set(task.failureAwareDependsOn ?? []);
+    for (const depId of task.depends_on) {
+        const record = upstream[depId];
+        const stdout = record?.stdout?.trim() ? record.stdout : "";
+        const assistantText = record?.assistantText?.trim()
+            ? record.assistantText
+            : "";
+        const stderr = record?.stderr?.trim() ? record.stderr : "";
+        const upstreamText = stdout || assistantText || stderr;
+        // AC1: a failure-aware recovery/diagnosis/closeout node may consume an
+        // upstream ERROR as settled failure evidence. Surface that evidence
+        // explicitly so the node can read the failure without the upstream being
+        // rewritten to FINISHED.
+        if (record?.status === "ERROR" &&
+            toleratedFailures.has(depId) &&
+            upstreamText) {
+            const { preview, truncated } = formatStdoutPreview(upstreamText, maxChars);
+            let section = `## Upstream failure evidence: ${depId} (status=ERROR${record.failureCategory
+                ? `, failureCategory=${record.failureCategory}`
+                : ""})\n${preview}`;
+            const artifactKind = stdout
+                ? "stdout"
+                : assistantText
+                    ? "assistant"
+                    : "stderr";
+            const artifactPath = artifactKind === "stdout"
+                ? record.stdoutArtifactPath
+                : artifactKind === "assistant"
+                    ? record.assistantArtifactPath
+                    : undefined;
+            if (truncated && artifactPath) {
+                section += formatUpstreamArtifactPointerMap(record, artifactKind === "stdout" ? "stdout" : "assistant");
+            }
+            else if (truncated && record.nodeRecordPath) {
+                section += [
+                    "",
+                    "Full failure record (read-only runner evidence — use read tool to fetch; do not edit):",
+                    `- node record: ${record.nodeRecordPath}`,
+                ].join("\n");
+            }
+            sections.push(section);
+            continue;
+        }
+        if (record?.status === "SKIPPED" && toleratedFailures.has(depId)) {
+            const reason = record.skippedReason ?? "unknown";
+            sections.push([
+                `## Upstream failure evidence: ${depId} (status=SKIPPED)`,
+                `Skipped reason: ${reason}`,
+                "This dependency was skipped after an upstream failure. Preserve the failed/partial_failed outcome and do not infer success.",
+            ].join("\n"));
+            continue;
+        }
+        if (!record || record.status !== "FINISHED" || !upstreamText)
+            continue;
+        const artifactKind = stdout ? "stdout" : "assistant";
+        const artifactPath = stdout
+            ? record.stdoutArtifactPath
+            : record.assistantArtifactPath;
+        const { preview, truncated } = formatStdoutPreview(upstreamText, maxChars);
+        let section = `## Upstream output: ${depId}\n${preview}`;
+        if (record.structuredArtifactPath) {
+            section += [
+                "",
+                "Validated structured artifact (read-only runner evidence — use read tool to fetch; do not edit):",
+                `- path: ${record.structuredArtifactPath}`,
+                `- schema: ${record.structuredArtifactSchemaId ?? "unknown"}`,
+                `- sha256: ${record.structuredArtifactSha256 ?? "unknown"}`,
+            ].join("\n");
+        }
+        if (truncated && artifactPath) {
+            section += formatUpstreamArtifactPointerMap(record, artifactKind);
+        }
+        sections.push(section);
+    }
+    return sections.join("\n\n");
+}
+function buildReadOnlyBoundary(writePolicy) {
+    if (writePolicy !== "read-only")
+        return [];
+    return [
+        "Read-only boundary: do not write, create, edit, delete, stage, or commit any repository files.",
+        "This includes root artifacts/**; root artifacts/ is not a read-only scratchpad.",
+        "Return findings in the assistant response/stdout only; the DAG runner persists node artifacts under .harness/dag-runs/<state>/<run-id>/<node-id>/.",
+    ];
+}
+/** Max chars for each text field in the convergence feedback block. */
+const CONVERGENCE_FEEDBACK_FIELD_MAX_CHARS = 600;
+/** Max chars for one list item/path in convergence feedback. */
+const CONVERGENCE_FEEDBACK_ITEM_MAX_CHARS = 240;
+/** Max items retained from an untrusted list-shaped feedback field. */
+const CONVERGENCE_FEEDBACK_LIST_MAX_ITEMS = 8;
+/** Hard cap for the complete rendered feedback block. */
+const CONVERGENCE_FEEDBACK_BLOCK_MAX_CHARS = 4_000;
+const CONVERGENCE_FEEDBACK_TRUNCATION_MARKER = "\n- [convergence feedback truncated]";
+function boundFeedbackText(value, maxChars = CONVERGENCE_FEEDBACK_FIELD_MAX_CHARS) {
+    if (!value)
+        return undefined;
+    if (value.length <= maxChars)
+        return value;
+    return `${value.slice(0, maxChars - 1)}…`;
+}
+function boundFeedbackList(values) {
+    const items = values
+        .slice(0, CONVERGENCE_FEEDBACK_LIST_MAX_ITEMS)
+        .map((value) => boundFeedbackText(value, CONVERGENCE_FEEDBACK_ITEM_MAX_CHARS) ?? "");
+    return {
+        items,
+        omitted: Math.max(0, values.length - items.length),
+    };
+}
+function capConvergenceFeedbackBlock(block) {
+    if (block.length <= CONVERGENCE_FEEDBACK_BLOCK_MAX_CHARS)
+        return block;
+    const prefixLength = Math.max(0, CONVERGENCE_FEEDBACK_BLOCK_MAX_CHARS -
+        CONVERGENCE_FEEDBACK_TRUNCATION_MARKER.length);
+    return `${block.slice(0, prefixLength)}${CONVERGENCE_FEEDBACK_TRUNCATION_MARKER}`;
+}
+/**
+ * Format the prior supervised convergence pass as a bounded, structured block
+ * for the next-round supervisor/repair node. Deterministic: uses
+ * preservedNodeRecordPath pointers written by the convergence controller, never
+ * run-directory guessing. Returns undefined when there is no prior pass.
+ */
+export function formatConvergenceFeedbackBlock(feedback) {
+    if (!feedback)
+        return undefined;
+    const lines = [];
+    lines.push(`## Previous convergence pass ${feedback.pass} (reason=${boundFeedbackText(feedback.reason)})`);
+    lines.push("This is the prior bounded-recovery pass that failed. Use it as authoritative evidence for this round; do not repeat a no-op or infer success.");
+    if (feedback.hardVerifyFailureCategory) {
+        lines.push(`- hardVerifyFailureCategory: ${boundFeedbackText(feedback.hardVerifyFailureCategory)}`);
+    }
+    if (feedback.processVerdict) {
+        lines.push(`- processVerdict: ${feedback.processVerdict}`);
+    }
+    if (feedback.reviewVerdict) {
+        lines.push(`- reviewVerdict: ${feedback.reviewVerdict}`);
+    }
+    if (feedback.reviewFailureCategory) {
+        lines.push(`- reviewFailureCategory: ${boundFeedbackText(feedback.reviewFailureCategory)}`);
+    }
+    if (feedback.shellSuccessCount !== undefined) {
+        lines.push(`- shellSuccessCount: ${feedback.shellSuccessCount}`);
+    }
+    const repair = feedback.repairArtifact;
+    if (repair) {
+        const parts = [];
+        if (repair.failureClass)
+            parts.push(`failureClass=${boundFeedbackText(repair.failureClass)}`);
+        if (repair.rootCause)
+            parts.push(`rootCause=${boundFeedbackText(repair.rootCause)}`);
+        if (repair.invariant)
+            parts.push(`invariant=${boundFeedbackText(repair.invariant)}`);
+        if (repair.fixScope && repair.fixScope.length > 0) {
+            const boundedScope = boundFeedbackList(repair.fixScope);
+            const omitted = boundedScope.omitted > 0
+                ? `, … (+${boundedScope.omitted} more)`
+                : "";
+            parts.push(`fixScope=${boundedScope.items.join(", ")}${omitted}`);
+        }
+        if (parts.length > 0)
+            lines.push(`- priorRepairArtifact: ${parts.join("; ")}`);
+    }
+    const refs = feedback.evidenceRefs.filter((ref) => ref.preservedNodeRecordPath);
+    if (refs.length > 0) {
+        lines.push("- previous failure evidence (read-only runner evidence — use read tool to fetch; do not edit):");
+        const boundedRefs = refs.slice(0, CONVERGENCE_FEEDBACK_LIST_MAX_ITEMS);
+        for (const ref of boundedRefs) {
+            lines.push(`  - ${boundFeedbackText(ref.nodeId, CONVERGENCE_FEEDBACK_ITEM_MAX_CHARS)}: ${boundFeedbackText(ref.preservedNodeRecordPath, CONVERGENCE_FEEDBACK_ITEM_MAX_CHARS)}`);
+        }
+        if (refs.length > boundedRefs.length) {
+            lines.push(`  - … (+${refs.length - boundedRefs.length} more)`);
+        }
+    }
+    return capConvergenceFeedbackBlock(lines.join("\n"));
+}
+function formatProjectGovernanceContext(ctx) {
+    if (!ctx || !ctx.applicable)
+        return undefined;
+    const lines = [];
+    lines.push("Deterministic project governance manifest for the actual writer changeset of this run. Interpret it for compliance review; do not invent rules beyond the files and hashes listed here.");
+    lines.push("Before issuing a verdict, use read-only tools to read every applicable AGENTS.md and every mandatory referenced standard listed below from the repository; hashes bind the exact inputs for audit.");
+    lines.push("Your first non-empty output line must be exactly VERDICT: pass or VERDICT: request-revision. Request revision while any applicable mandatory instruction is violated.");
+    lines.push("");
+    lines.push("Change manifest (writer nodes and their changed files):");
+    for (const entry of ctx.changeManifest) {
+        if (entry.changedFiles.length === 0)
+            continue;
+        lines.push(`- ${entry.writerNodeId}: ${entry.changedFiles.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("Applicable AGENTS.md chain (root -> nearest):");
+    for (const entry of ctx.agentsMdChain) {
+        lines.push(`- ${entry.path} (enforcement=mandatory, directory=${entry.directory || "/"}, sha256=${entry.sha256}, bytes=${entry.bytes}) applies to: ${entry.appliesTo.join(", ") || "(none)"}`);
+    }
+    if (ctx.referencedStandards.length > 0) {
+        lines.push("");
+        lines.push("Referenced repository-local code standards:");
+        for (const std of ctx.referencedStandards) {
+            lines.push(`- ${std.path} (enforcement=${std.enforcement}, from ${ctx.agentsMdChain[std.fromAgentsMd]?.path ?? "AGENTS.md"}, sha256=${std.sha256}, bytes=${std.bytes}, scope=${std.scope})`);
+        }
+    }
+    if (ctx.unresolvedReferences.length > 0) {
+        lines.push("");
+        lines.push("Unresolved reference diagnostics (structured, not read): for awareness only.");
+        for (const ref of ctx.unresolvedReferences) {
+            lines.push(`- ${ref.declaredPath}: ${ref.reason} (from ${ctx.agentsMdChain[ref.fromAgentsMd]?.path ?? "AGENTS.md"})`);
+        }
+    }
+    if (ctx.diagnostics.length > 0) {
+        lines.push("");
+        lines.push("Resolver diagnostics:");
+        for (const diag of ctx.diagnostics)
+            lines.push(`- ${diag}`);
+    }
+    return lines.join("\n");
+}
+export function buildDagNodePromptEnvelope(input) {
+    const { spec, task, upstream, resolvedSkills = [], resolvedSkillInstructions = [], maxUpstreamChars = MAX_UPSTREAM_CHARS, projectGovernanceContext, convergenceFeedback, } = input;
+    const objective = spec.objective ?? spec.title;
+    const successCriteria = formatBulletList(spec.successCriteria, "(none specified)");
+    const globalConstraints = formatBulletList(spec.globalConstraints, "(none specified)");
+    const role = task.role ?? "(not specified)";
+    const writePolicy = resolveWritePolicy(task, spec);
+    const skillsSection = resolvedSkills.length > 0
+        ? resolvedSkills.map((skill) => `- ${skill}`).join("\n")
+        : "(none)";
+    const skillInstructionsSection = formatResolvedSkillInstructions(resolvedSkillInstructions);
+    const upstreamContext = buildUpstreamContext(task, upstream, maxUpstreamChars);
+    const readOnlyBoundary = buildReadOnlyBoundary(writePolicy);
+    const sections = [
+        `<dag_objective>\n${objective}\n</dag_objective>`,
+        `<success_criteria>\n${successCriteria}\n</success_criteria>`,
+        `<global_constraints>\n${globalConstraints}\n</global_constraints>`,
+        `<output_language>\n${formatOutputLanguageBlock(spec.outputLanguage)}\n</output_language>`,
+        [
+            "<node_contract>",
+            `Role: ${role}`,
+            `Executor: ${formatExecutor(task)}`,
+            `Write policy: ${writePolicy}`,
+            `Allowed paths: ${formatPaths(task.allowedPaths)}`,
+            `Forbidden paths: ${formatPaths(task.forbiddenPaths)}`,
+            `Write set: ${formatPaths(task.writeSet)}`,
+            `Output contract: ${resolveOutputContract(task)}`,
+            ...readOnlyBoundary,
+            "</node_contract>",
+        ].join("\n"),
+        [
+            "<required_skills>",
+            "Before acting, apply the following skills:",
+            skillsSection,
+            "</required_skills>",
+        ].join("\n"),
+        [
+            "<resolved_skill_instructions>",
+            "The DAG runner resolved these skill files deterministically. Apply the bounded instructions below when present. Missing/error entries mean only the skill name is available; do not assume hidden Pi ResourceLoader skills.",
+            skillInstructionsSection,
+            "</resolved_skill_instructions>",
+        ].join("\n"),
+    ];
+    if (task.role && PLANNER_AUTHORING_ROLES.has(task.role)) {
+        sections.push(`<authoring_guidance>\n${formatAuthoringGuidanceBlock()}\n</authoring_guidance>`);
+    }
+    if (upstreamContext) {
+        sections.push(`<upstream_context>\n${upstreamContext}\n</upstream_context>`);
+    }
+    else {
+        sections.push("<upstream_context>\n(none)\n</upstream_context>");
+    }
+    const governanceSection = formatProjectGovernanceContext(projectGovernanceContext);
+    if (governanceSection) {
+        sections.push(`<project_governance_context>\n${governanceSection}\n</project_governance_context>`);
+    }
+    // Only supervisor/repair nodes consume the prior convergence pass evidence.
+    // This keeps the bounded-recovery loop from repeating no-ops on round 2+.
+    if (convergenceFeedback &&
+        (task.role === "supervisor" ||
+            task.role === "implementer" ||
+            task.id === "process-supervisor-pi" ||
+            task.id === "repair-pi")) {
+        const feedbackSection = formatConvergenceFeedbackBlock(convergenceFeedback);
+        if (feedbackSection) {
+            sections.push(`<convergence_feedback>\n${feedbackSection}\n</convergence_feedback>`);
+        }
+    }
+    sections.push(`<task>\n${task.subtask_prompt}\n</task>`);
+    return sections.join("\n\n");
+}

package/dist/workflows/dag/reconcile-run.js

@@ -0,0 +1,145 @@
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { assessDagRunLiveness, assessDagRunRecoveryEligibility, assertDagRunTransferTargetAvailable, getDagRunDir, locateDagRun, readDagRunState, transferDagRunDir, writeDagRunState, } from "./lifecycle.js";
+export function parseDagReconcileRunArgs(args) {
+    let runId;
+    let action;
+    let reason;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--run-id")
+            runId = args[++index];
+        else if (arg.startsWith("--run-id="))
+            runId = arg.slice("--run-id=".length);
+        else if (arg === "--action")
+            action = parseAction(args[++index]);
+        else if (arg.startsWith("--action="))
+            action = parseAction(arg.slice("--action=".length));
+        else if (arg === "--reason")
+            reason = args[++index];
+        else if (arg.startsWith("--reason="))
+            reason = arg.slice("--reason=".length);
+        else if (arg.startsWith("-"))
+            throw new Error(`unknown dag reconcile-run flag: ${arg}`);
+        else
+            throw new Error(`unexpected positional argument: ${arg}`);
+    }
+    if (!runId)
+        throw new Error("dag reconcile-run requires --run-id <id>");
+    if (action && !reason?.trim()) {
+        throw new Error("dag reconcile-run mutation requires --reason <text>");
+    }
+    return { runId, action, ...(reason?.trim() ? { reason: reason.trim() } : {}) };
+}
+function parseAction(value) {
+    if (value === "supersede" || value === "abandon")
+        return value;
+    throw new Error("dag reconcile-run --action must be supersede or abandon");
+}
+/**
+ * DAG-kernel reconcile for a single run. Lives in workflows so Worker outer-loop
+ * recovery can call it without importing the CLI/commands layer.
+ */
+export async function executeDagReconcileRun(repoRoot, rawArgs) {
+    const parsed = parseDagReconcileRunArgs(rawArgs);
+    const located = await locateDagRun(repoRoot, parsed.runId);
+    if (!located)
+        throw new Error(`dag run not found: ${parsed.runId}`);
+    const state = await readDagRunState(located.runDir);
+    const liveness = assessDagRunLiveness({ state });
+    const eligibility = assessDagRunRecoveryEligibility({
+        lifecycle: located.lifecycle,
+        state,
+        liveness: liveness.status,
+    });
+    if (!parsed.action) {
+        return {
+            action: "inspect",
+            runId: state.runId,
+            lifecycle: located.lifecycle,
+            status: state.status,
+            liveness: liveness.status,
+            eligibility,
+            nextRecommendedAction: eligibility.canReconcile
+                ? "Re-run with --action supersede|abandon and --reason <text>."
+                : "Do not reconcile this run; inspect runner and lifecycle evidence first.",
+        };
+    }
+    if (!eligibility.canReconcile || !eligibility.allowedActions.includes(parsed.action)) {
+        throw new Error(`dag run ${state.runId} is not eligible for reconciliation: ${eligibility.reasons.join(", ") || "unknown reason"}`);
+    }
+    const reconciledAt = new Date().toISOString();
+    const completedRunDir = getDagRunDir(repoRoot, "completed", state.runId);
+    if (located.lifecycle !== "completed") {
+        await assertDagRunTransferTargetAvailable(completedRunDir);
+    }
+    const artifactRelativePath = path.join(".harness", "dag-runs", "completed", state.runId, "reconciliation.json").replace(/\\/g, "/");
+    await writeJsonAtomic(path.join(located.runDir, "reconciliation.json"), {
+        schemaVersion: 1,
+        runId: state.runId,
+        action: parsed.action,
+        reason: parsed.reason,
+        reconciledAt,
+        previousLifecycle: located.lifecycle,
+        previousStatus: state.status,
+        liveness: liveness.status,
+        originalState: state,
+    });
+    const previousStatus = state.status;
+    for (const node of Object.values(state.nodes)) {
+        if (node.status !== "RUNNING")
+            continue;
+        node.status = "ERROR";
+        node.finishedAt = reconciledAt;
+        const elapsedNodeMs = elapsedDurationMs(node.startedAt, reconciledAt);
+        if (elapsedNodeMs !== undefined) {
+            node.durationMs = Math.max(node.durationMs ?? 0, elapsedNodeMs);
+        }
+        const attemptsNewestFirst = node.attempts?.slice().reverse() ?? [];
+        const currentAttempt = attemptsNewestFirst.find((attempt) => attempt.attempt === node.currentAttempt &&
+            attempt.finishedAt === undefined) ?? attemptsNewestFirst.find((attempt) => attempt.finishedAt === undefined);
+        if (currentAttempt && currentAttempt.finishedAt === undefined) {
+            currentAttempt.finishedAt = reconciledAt;
+            const elapsedAttemptMs = elapsedDurationMs(currentAttempt.startedAt, reconciledAt);
+            if (elapsedAttemptMs !== undefined) {
+                currentAttempt.durationMs = Math.max(currentAttempt.durationMs ?? 0, elapsedAttemptMs);
+            }
+            currentAttempt.failureCategory = `operator-${parsed.action}`;
+        }
+        node.failureCategory = `operator-${parsed.action}`;
+    }
+    state.status = parsed.action === "supersede" ? "superseded" : "abandoned";
+    state.finishedAt = reconciledAt;
+    state.failureCategory = `operator-${parsed.action}`;
+    state.reconciliation = {
+        action: parsed.action,
+        reason: parsed.reason,
+        reconciledAt,
+        previousStatus,
+        previousLifecycle: located.lifecycle,
+        liveness: liveness.status,
+        artifactPath: artifactRelativePath,
+    };
+    await writeDagRunState(located.runDir, state);
+    const runDir = located.lifecycle === "completed"
+        ? located.runDir
+        : await transferDagRunDir(located.runDir, completedRunDir);
+    return {
+        action: parsed.action,
+        runId: state.runId,
+        status: state.status,
+        lifecycle: "completed",
+        reason: parsed.reason,
+        reconciliationArtifactPath: artifactRelativePath,
+        runDir,
+    };
+}
+function elapsedDurationMs(startedAt, finishedAt) {
+    if (!startedAt)
+        return undefined;
+    const started = Date.parse(startedAt);
+    const finished = Date.parse(finishedAt);
+    if (!Number.isFinite(started) || !Number.isFinite(finished))
+        return undefined;
+    return Math.max(0, finished - started);
+}