@tea-agent/loop-agent 0.26.5-beta.2 → 0.27.0

package/dist/application/task-lifecycle/advance.js

@@ -0,0 +1,845 @@
+import { access, copyFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { createTask, getTaskPaths, loadTaskConfig, } from "../../task/runtime.js";
+import { importPrdDocument } from "../../task/source-references.js";
+import { prepareTaskSource } from "../../task/source-prepare/index.js";
+import { logicalRevisionForState, observeTaskContractState, recoverTaskContract, } from "../../task/contract/index.js";
+import { generateTaskDagUseCase } from "../dag/generate-task-dag.js";
+import { validateDagUseCase } from "../dag/validate-dag.js";
+import { runDagUseCase } from "../dag/run-dag.js";
+import { promoteRunEvidence, closeoutTask } from "../../records/promotion.js";
+import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
+import { assessDagRunLiveness, locateDagRun, readDagRunState, } from "../../workflows/dag/lifecycle.js";
+import { buildGateBinding, buildWriteSetGate, controllerIdentityAnchor, gateMatches, hashCanonicalPayload, parseGateToken, } from "./gates.js";
+import { appendTransition, emptyLifecycleRecord, loadLifecycleRecord, recordRunAssociation, saveLifecycleRecord, } from "./record.js";
+import { collectNormalizedWriteSetFromSpec, hashDagSpecFileContent, observeTaskLifecycle, } from "./observe.js";
+import { planTransitions, } from "./plan-transitions.js";
+import { applyAcceptedRecommendations, buildTaskLifecycleRecommendations, } from "./recommendations.js";
+const ATTENTION_LIVENESS = new Set([
+    "orphaned",
+    "stale",
+    "needs-attention",
+    "suspected-stall",
+]);
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasEngineeringBoundary(input) {
+    return Boolean((input.allowedPaths && input.allowedPaths.length > 0) ||
+        (input.forbiddenPaths && input.forbiddenPaths.length > 0) ||
+        (input.verifyCommands && input.verifyCommands.length > 0) ||
+        input.fromText ||
+        input.fromDraftPath);
+}
+function uniqueTransitions(existing, extra) {
+    const set = new Set(existing);
+    for (const item of extra)
+        set.add(item);
+    return [...set];
+}
+function extractMeaningfulProgressAt(state) {
+    const activeNode = Object.values(state.nodes ?? {}).find((node) => node.status === "RUNNING");
+    if (activeNode) {
+        return (activeNode.lastMeaningfulProgressAt ??
+            activeNode.lastProviderActivityAt ??
+            activeNode.lastToolActivityAt ??
+            activeNode.lastOutputActivityAt ??
+            activeNode.lastActivityAt ??
+            activeNode.startedAt ??
+            null);
+    }
+    const latestFinished = Object.values(state.nodes ?? {})
+        .filter((node) => node.finishedAt || node.startedAt)
+        .sort((a, b) => String(b.finishedAt ?? b.startedAt ?? "").localeCompare(String(a.finishedAt ?? a.startedAt ?? "")))[0];
+    return (latestFinished?.lastMeaningfulProgressAt ??
+        latestFinished?.finishedAt ??
+        latestFinished?.startedAt ??
+        null);
+}
+function toRunAssociation(input) {
+    return {
+        runId: input.runId,
+        lifecycle: input.lifecycle,
+        runDir: input.runDir,
+        status: input.state.status,
+        failureCategory: input.failureCategory ?? input.state.failureCategory ?? null,
+        lastMeaningfulProgressAt: extractMeaningfulProgressAt(input.state),
+        source: input.source ?? "lifecycle-record",
+    };
+}
+async function buildCurrentGate(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    if (!(await pathExists(paths.dagDraftPath)))
+        return null;
+    const raw = await readFile(paths.dagDraftPath, "utf-8");
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const contractState = await observeTaskContractState(repoRoot, taskId);
+    const identity = resolveRunningControllerIdentity();
+    let writeSet = collectNormalizedWriteSetFromSpec(spec);
+    if (writeSet.length === 0) {
+        try {
+            const config = await loadTaskConfig(repoRoot, taskId);
+            writeSet = config.allowedPaths ?? [];
+        }
+        catch {
+            // leave empty
+        }
+    }
+    const bound = buildGateBinding({
+        taskId,
+        contractRevision: logicalRevisionForState(contractState),
+        contractCanonicalHash: contractState.ref?.canonicalHash ??
+            contractState.observedCanonicalHash ??
+            null,
+        sourceBindingHash: spec.sourceBinding
+            ? hashCanonicalPayload(spec.sourceBinding)
+            : null,
+        dagSpecHash: hashDagSpecFileContent(raw),
+        writeSet,
+        controllerIdentityAnchor: controllerIdentityAnchor(identity
+            ? {
+                packageName: identity.packageName,
+                packageVersion: identity.packageVersion,
+                packageFingerprintValue: identity.packageFingerprint.value,
+            }
+            : null),
+    });
+    return buildWriteSetGate({ taskId, bound });
+}
+async function monitorRun(input) {
+    const started = Date.now();
+    while (Date.now() - started < input.timeoutMs) {
+        const located = await locateDagRun(input.repoRoot, input.runId);
+        if (!located) {
+            throw new Error(`run not found while monitoring: ${input.runId}`);
+        }
+        const state = await readDagRunState(located.runDir);
+        const liveness = assessDagRunLiveness({ state });
+        const meaningfulAt = extractMeaningfulProgressAt(state);
+        input.onProgress?.(`monitoring run ${input.runId} lifecycle=${located.lifecycle} status=${state.status} liveness=${liveness.status} meaningful=${meaningfulAt ?? "n/a"}`);
+        if (located.lifecycle === "completed" || located.lifecycle === "paused") {
+            return toRunAssociation({
+                runId: input.runId,
+                lifecycle: located.lifecycle,
+                runDir: located.runDir,
+                state,
+            });
+        }
+        if (state.status === "finished" || state.status === "failed") {
+            return toRunAssociation({
+                runId: input.runId,
+                lifecycle: located.lifecycle,
+                runDir: located.runDir,
+                state,
+            });
+        }
+        if (ATTENTION_LIVENESS.has(liveness.status)) {
+            return toRunAssociation({
+                runId: input.runId,
+                lifecycle: located.lifecycle,
+                runDir: located.runDir,
+                state,
+                failureCategory: state.failureCategory ??
+                    (liveness.status === "orphaned"
+                        ? "orphaned"
+                        : liveness.status === "stale"
+                            ? "stale-heartbeat"
+                            : liveness.status),
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, input.intervalMs));
+    }
+    const located = await locateDagRun(input.repoRoot, input.runId);
+    if (!located) {
+        throw new Error(`run not found after monitor timeout: ${input.runId}`);
+    }
+    const state = await readDagRunState(located.runDir);
+    return toRunAssociation({
+        runId: input.runId,
+        lifecycle: located.lifecycle,
+        runDir: located.runDir,
+        state,
+        failureCategory: "monitor-timeout",
+    });
+}
+function nextMutationAction(actions) {
+    for (const action of actions) {
+        if (action.type !== "stop")
+            return action;
+    }
+    return actions[0] ?? null;
+}
+export async function advanceTaskLifecycle(input) {
+    const completed = [];
+    const blockers = [];
+    const warnings = [];
+    let promotion = null;
+    let closeout = null;
+    let run = null;
+    let consumeApproveGate = Boolean(input.approveGateToken);
+    /** After a successful approve, keep approve intent for finalize replan only. */
+    let approvedThisCall = false;
+    /**
+     * import-prd runs once per invocation when --prd is provided. Without this
+     * latch, re-plan keeps scheduling import-prd first (hasPrd stays true) and
+     * never reaches prepare-contract / gate.
+     */
+    let importedPrdThisCall = false;
+    let snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+    let record = (await loadLifecycleRecord(input.repoRoot, input.taskId)) ??
+        emptyLifecycleRecord(input.taskId);
+    const hasPrd = Boolean(input.prdPaths && input.prdPaths.length > 0);
+    const dryRun = Boolean(input.dryRun);
+    // P1 deterministic recommendations (never auto-elevated without digest accept).
+    const prdTexts = [];
+    for (const prd of input.prdPaths ?? []) {
+        try {
+            prdTexts.push(await readFile(path.resolve(prd.filePath), "utf-8"));
+        }
+        catch {
+            // ignore unreadable PRD for recommendation purposes
+        }
+    }
+    const recommendations = await buildTaskLifecycleRecommendations({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+        prdTexts,
+    });
+    const applied = applyAcceptedRecommendations({
+        recommendations,
+        acceptDigest: input.acceptRecommendationsDigest,
+        explicitAllowedPaths: input.allowedPaths,
+        explicitVerifyCommands: input.verifyCommands,
+    });
+    if (applied.staleAccept) {
+        return {
+            taskId: input.taskId,
+            lifecycleState: snapshot.lifecycleState,
+            completedTransitions: record.completedTransitions,
+            gate: snapshot.gate,
+            blockers: [
+                {
+                    code: "STALE_RECOMMENDATIONS",
+                    message: "--accept-recommendations digest does not match current recommendations",
+                    details: { expectedDigest: recommendations.digest },
+                },
+            ],
+            warnings,
+            next: {
+                kind: "advance",
+                command: `loop-agent task advance ${input.taskId} --json`,
+            },
+            dryRun,
+            recommendations,
+        };
+    }
+    const effectiveInput = {
+        ...input,
+        allowedPaths: applied.allowedPaths ?? input.allowedPaths,
+        verifyCommands: applied.verifyCommands ?? input.verifyCommands,
+    };
+    const hasBoundary = hasEngineeringBoundary(effectiveInput);
+    if (applied.accepted) {
+        warnings.push({
+            code: "RECOMMENDATIONS_ACCEPTED",
+            message: `accepted recommendations digest ${recommendations.digest}`,
+        });
+        const elevatedPaths = applied.allowedPaths?.length ?? 0;
+        if (elevatedPaths === 0) {
+            warnings.push({
+                code: "RECOMMENDATIONS_PATHS_STILL_REQUIRED",
+                message: "accepted recommendations elevated verifyCommands only; provide --allowed-path (PRD path tokens remain weak candidates and are not auto-elevated)",
+            });
+        }
+    }
+    // Reject gate path
+    if (input.rejectGateToken) {
+        if (!input.rejectReason?.trim()) {
+            return {
+                taskId: input.taskId,
+                lifecycleState: snapshot.lifecycleState,
+                completedTransitions: record.completedTransitions,
+                gate: snapshot.gate,
+                blockers: [
+                    {
+                        code: "REJECT_REASON_REQUIRED",
+                        message: "--reason is required with --reject-gate",
+                    },
+                ],
+                warnings,
+                next: snapshot.next,
+                recommendations,
+            };
+        }
+        const token = parseGateToken(input.rejectGateToken);
+        const currentGate = snapshot.gate ?? (await buildCurrentGate(input.repoRoot, input.taskId));
+        if (!currentGate || !gateMatches(currentGate, token)) {
+            return {
+                taskId: input.taskId,
+                lifecycleState: "awaiting-write-set-approval",
+                completedTransitions: record.completedTransitions,
+                gate: currentGate,
+                blockers: [
+                    {
+                        code: "STALE_GATE",
+                        message: "reject gate digest does not match current snapshot",
+                    },
+                ],
+                warnings,
+                next: currentGate
+                    ? { kind: "approve-gate", command: currentGate.approveCommand }
+                    : {
+                        kind: "advance",
+                        command: `loop-agent task advance ${input.taskId} --json`,
+                    },
+                recommendations,
+            };
+        }
+        if (!dryRun) {
+            record = appendTransition(record, "write-set-rejected");
+            record = {
+                ...record,
+                lastGate: {
+                    id: currentGate.id,
+                    digest: currentGate.digest,
+                    bound: currentGate.bound,
+                    status: "rejected",
+                    reason: input.rejectReason,
+                },
+            };
+            await saveLifecycleRecord(input.repoRoot, record);
+            completed.push("write-set-rejected");
+        }
+        return {
+            taskId: input.taskId,
+            lifecycleState: "intake-incomplete",
+            completedTransitions: uniqueTransitions(record.completedTransitions, completed),
+            gate: null,
+            blockers: [],
+            warnings,
+            next: {
+                kind: "advance",
+                command: `loop-agent task advance ${input.taskId} --json`,
+            },
+            dryRun,
+            recommendations,
+        };
+    }
+    const planOnce = (current) => planTransitions({
+        snapshot: current,
+        hasPrdInput: hasPrd && !importedPrdThisCall,
+        hasEngineeringBoundary: hasBoundary,
+        approveGate: consumeApproveGate || approvedThisCall,
+        rejectGate: false,
+        dryRun,
+        skipFinalize: Boolean(input.skipFinalize),
+        forcePrepareContract: Boolean(input.fromDraftPath),
+    });
+    if (dryRun) {
+        const plan = planOnce(snapshot);
+        const plannedGate = snapshot.gate ??
+            (snapshot.dagDraft?.exists
+                ? await buildCurrentGate(input.repoRoot, input.taskId)
+                : null);
+        return {
+            taskId: input.taskId,
+            lifecycleState: snapshot.lifecycleState,
+            completedTransitions: record.completedTransitions,
+            gate: plannedGate,
+            blockers: plan.blockers,
+            warnings,
+            next: plan.next,
+            dryRun: true,
+            plannedTransitions: plan.expectedTransitions,
+            recommendations,
+        };
+    }
+    // Re-plan after every successful transition until a stop condition.
+    const maxSteps = 32;
+    for (let step = 0; step < maxSteps; step += 1) {
+        const plan = planOnce(snapshot);
+        const action = nextMutationAction(plan.actions);
+        if (!action || action.type === "stop") {
+            if (action?.type === "stop" && action.reason === "blocker") {
+                const softCodes = new Set(["INTAKE_REQUIRED", "BOUNDARY_REQUIRED"]);
+                const soft = plan.blockers.filter((b) => softCodes.has(b.code));
+                if (soft.length > 0 &&
+                    (completed.includes("task-created") ||
+                        completed.includes("prd-imported"))) {
+                    snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+                    return {
+                        taskId: input.taskId,
+                        lifecycleState: "intake-incomplete",
+                        completedTransitions: uniqueTransitions(record.completedTransitions, completed),
+                        gate: null,
+                        blockers: [],
+                        warnings: [
+                            ...warnings,
+                            ...soft.map((b) => ({
+                                code: b.code,
+                                message: b.message,
+                            })),
+                        ],
+                        next: plan.next,
+                        recommendations,
+                    };
+                }
+                blockers.push(...plan.blockers);
+            }
+            break;
+        }
+        if (action.type === "create-task") {
+            if (!snapshot.exists) {
+                await createTask(input.repoRoot, input.taskId, input.title);
+                record = appendTransition(record, "task-created");
+                completed.push("task-created");
+                await saveLifecycleRecord(input.repoRoot, record);
+            }
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            continue;
+        }
+        if (action.type === "recover-contract") {
+            await recoverTaskContract({
+                repoRoot: input.repoRoot,
+                taskId: input.taskId,
+            });
+            record = appendTransition(record, "contract-recovered");
+            completed.push("contract-recovered");
+            await saveLifecycleRecord(input.repoRoot, record);
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            continue;
+        }
+        if (action.type === "import-prd") {
+            for (const prd of input.prdPaths ?? []) {
+                await importPrdDocument({
+                    repoRoot: input.repoRoot,
+                    taskId: input.taskId,
+                    filePath: prd.filePath,
+                    role: prd.role,
+                });
+            }
+            // Latch even when prdPaths is empty so a mis-planned import cannot loop.
+            importedPrdThisCall = true;
+            if ((input.prdPaths?.length ?? 0) > 0) {
+                record = appendTransition(record, "prd-imported");
+                completed.push("prd-imported");
+                await saveLifecycleRecord(input.repoRoot, record);
+            }
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            continue;
+        }
+        if (action.type === "prepare-contract") {
+            let draftIntent = null;
+            if (input.fromDraftPath) {
+                try {
+                    const draftRaw = await readFile(path.resolve(input.fromDraftPath), "utf-8");
+                    draftIntent = {
+                        kind: "draft",
+                        draft: JSON.parse(draftRaw),
+                        sourcePath: input.fromDraftPath,
+                    };
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    blockers.push({
+                        code: "INVALID_DRAFT",
+                        message: `failed to parse --from-draft: ${message}`,
+                    });
+                    break;
+                }
+            }
+            const prepareResult = await prepareTaskSource({
+                repoRoot: input.repoRoot,
+                taskId: input.taskId,
+                mode: "apply",
+                intent: draftIntent
+                    ? {
+                        kind: "draft",
+                        draft: draftIntent.draft,
+                        sourcePath: draftIntent.sourcePath,
+                    }
+                    : {
+                        kind: "facts",
+                        useImportedPrd: hasPrd || (snapshot.source?.importedPrdCount ?? 0) > 0,
+                        text: input.fromText,
+                        textLabel: input.fromText ? "from-text" : undefined,
+                    },
+                flags: {
+                    title: input.title,
+                    taskKind: input.taskKind,
+                    featureId: input.featureId,
+                    allowedPaths: effectiveInput.allowedPaths,
+                    forbiddenPaths: input.forbiddenPaths,
+                    verifyCommands: effectiveInput.verifyCommands,
+                },
+            });
+            if (!prepareResult.ok) {
+                blockers.push({
+                    code: prepareResult.error?.code ?? "PREPARE_FAILED",
+                    message: prepareResult.error?.message ?? "task source prepare failed",
+                    details: {
+                        gaps: prepareResult.gaps,
+                        outcome: prepareResult.outcome,
+                    },
+                });
+                break;
+            }
+            record = appendTransition(record, "contract-managed");
+            completed.push("contract-managed");
+            await saveLifecycleRecord(input.repoRoot, record);
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            continue;
+        }
+        if (action.type === "generate-dag") {
+            try {
+                const profile = input.profile ?? "auto";
+                const generated = await generateTaskDagUseCase({
+                    repoRoot: input.repoRoot,
+                    taskId: input.taskId,
+                    strictModels: input.strictModels ?? true,
+                    execute: false,
+                    initOnly: false,
+                    dryRun: false,
+                    cwd: input.repoRoot,
+                    profile,
+                    profileExplicit: input.profileExplicit ??
+                        Boolean(input.profile && input.profile !== "auto"),
+                    ...(input.maxConcurrent !== undefined
+                        ? { maxConcurrent: input.maxConcurrent }
+                        : {}),
+                });
+                if (!("outputPath" in generated)) {
+                    blockers.push({
+                        code: "DAG_GENERATE_FAILED",
+                        message: "dag generation did not produce an output path",
+                    });
+                    break;
+                }
+                if (input.dagOutputPath) {
+                    await mkdir(path.dirname(input.dagOutputPath), { recursive: true });
+                    await copyFile(generated.outputPath, input.dagOutputPath);
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                blockers.push({
+                    code: "DAG_GENERATE_FAILED",
+                    message,
+                });
+                break;
+            }
+            record = appendTransition(record, "dag-generated");
+            completed.push("dag-generated");
+            await saveLifecycleRecord(input.repoRoot, record);
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            continue;
+        }
+        if (action.type === "strict-validate-dag") {
+            try {
+                const paths = getTaskPaths(input.repoRoot, input.taskId);
+                const validation = await validateDagUseCase({
+                    repoRoot: input.repoRoot,
+                    dagPath: paths.dagDraftPath,
+                    strictModelMatrix: input.strictModels ?? true,
+                    strictGovernance: true,
+                    forbidExecutors: [],
+                });
+                const raw = await readFile(paths.dagDraftPath, "utf-8");
+                const specHash = hashDagSpecFileContent(raw);
+                record = appendTransition(record, "dag-strict-validated");
+                record = {
+                    ...record,
+                    lastDagSpecHash: specHash,
+                    strictValidatedAt: new Date().toISOString(),
+                };
+                completed.push("dag-strict-validated");
+                if (validation.warnings?.length) {
+                    for (const warning of validation.warnings) {
+                        warnings.push({
+                            code: "DAG_VALIDATE_WARNING",
+                            message: "message" in warning
+                                ? String(warning.message)
+                                : JSON.stringify(warning),
+                        });
+                    }
+                }
+                await saveLifecycleRecord(input.repoRoot, record);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                blockers.push({
+                    code: "DAG_VALIDATE_FAILED",
+                    message,
+                });
+                break;
+            }
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            continue;
+        }
+        if (action.type === "open-write-set-gate") {
+            const gate = await buildCurrentGate(input.repoRoot, input.taskId);
+            if (!gate) {
+                blockers.push({
+                    code: "GATE_UNAVAILABLE",
+                    message: "unable to build write-set gate; ensure DAG draft exists",
+                });
+                break;
+            }
+            record = appendTransition(record, "write-set-gate-opened");
+            record = {
+                ...record,
+                lastGate: {
+                    id: gate.id,
+                    digest: gate.digest,
+                    bound: gate.bound,
+                    status: "open",
+                },
+            };
+            completed.push("write-set-gate-opened");
+            await saveLifecycleRecord(input.repoRoot, record);
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            // Stop before writers.
+            return {
+                taskId: input.taskId,
+                lifecycleState: "awaiting-write-set-approval",
+                completedTransitions: uniqueTransitions(record.completedTransitions, completed),
+                gate,
+                blockers,
+                warnings,
+                next: {
+                    kind: "approve-gate",
+                    command: gate.approveCommand,
+                },
+                recommendations,
+            };
+        }
+        if (action.type === "start-or-monitor-run") {
+            // Validate approval digest if provided.
+            if (consumeApproveGate && input.approveGateToken) {
+                const token = parseGateToken(input.approveGateToken);
+                const currentGate = snapshot.gate ??
+                    (await buildCurrentGate(input.repoRoot, input.taskId));
+                if (!currentGate || !gateMatches(currentGate, token)) {
+                    const freshGate = currentGate ??
+                        (await buildCurrentGate(input.repoRoot, input.taskId));
+                    return {
+                        taskId: input.taskId,
+                        lifecycleState: "awaiting-write-set-approval",
+                        completedTransitions: uniqueTransitions(record.completedTransitions, completed),
+                        gate: freshGate,
+                        blockers: [
+                            {
+                                code: "STALE_GATE",
+                                message: "approve gate digest does not match current contract/DAG/writeSet/controller binding",
+                            },
+                        ],
+                        warnings,
+                        next: freshGate
+                            ? { kind: "approve-gate", command: freshGate.approveCommand }
+                            : {
+                                kind: "advance",
+                                command: `loop-agent task advance ${input.taskId} --json`,
+                            },
+                        recommendations,
+                    };
+                }
+                record = appendTransition(record, "write-set-approved");
+                record = {
+                    ...record,
+                    lastGate: {
+                        id: currentGate.id,
+                        digest: currentGate.digest,
+                        bound: currentGate.bound,
+                        status: "approved",
+                    },
+                };
+                completed.push("write-set-approved");
+                await saveLifecycleRecord(input.repoRoot, record);
+                consumeApproveGate = false;
+                approvedThisCall = true;
+            }
+            // If already active, only monitor.
+            if (snapshot.activeRun) {
+                run = await monitorRun({
+                    repoRoot: input.repoRoot,
+                    runId: snapshot.activeRun.runId,
+                    intervalMs: input.monitorIntervalMs ?? 5_000,
+                    timeoutMs: input.monitorTimeoutMs ?? 24 * 60 * 60 * 1000,
+                    onProgress: input.onProgress,
+                });
+                record = appendTransition(record, "dag-run-monitored");
+                record = recordRunAssociation(record, {
+                    runId: run.runId,
+                    source: "lifecycle-record",
+                });
+                completed.push("dag-run-monitored");
+                if (run.failureCategory === "monitor-timeout" ||
+                    run.failureCategory === "orphaned" ||
+                    run.failureCategory === "stale-heartbeat" ||
+                    run.failureCategory === "needs-attention" ||
+                    run.failureCategory === "suspected-stall" ||
+                    run.failureCategory === "termination-unconfirmed") {
+                    await saveLifecycleRecord(input.repoRoot, record);
+                    snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+                    blockers.push({
+                        code: "RUN_NEEDS_ATTENTION",
+                        message: `active run ${run.runId} requires attention (${run.failureCategory})`,
+                        details: {
+                            runId: run.runId,
+                            failureCategory: run.failureCategory,
+                            status: run.status,
+                        },
+                    });
+                    break;
+                }
+                if (run.lifecycle === "completed" || run.status === "finished") {
+                    if (run.status === "finished") {
+                        record = appendTransition(record, "run-succeeded");
+                        completed.push("run-succeeded");
+                    }
+                    else {
+                        record = appendTransition(record, "run-failed");
+                        completed.push("run-failed");
+                    }
+                }
+                await saveLifecycleRecord(input.repoRoot, record);
+            }
+            else {
+                const paths = getTaskPaths(input.repoRoot, input.taskId);
+                const result = await runDagUseCase({
+                    repoRoot: input.repoRoot,
+                    dagPath: paths.dagDraftPath,
+                    cwd: input.repoRoot,
+                    initOnly: false,
+                    dryRun: false,
+                    ...(input.maxConcurrent !== undefined
+                        ? { maxConcurrent: input.maxConcurrent }
+                        : {}),
+                    ...(input.runId ? { runId: input.runId } : {}),
+                    ...(input.eventsJsonlPath
+                        ? { eventsJsonlPath: input.eventsJsonlPath }
+                        : {}),
+                    ...(input.workerAssociation
+                        ? { workerAssociation: input.workerAssociation }
+                        : {}),
+                });
+                const runId = result.runId;
+                record = appendTransition(record, "dag-run-started");
+                record = recordRunAssociation(record, {
+                    runId,
+                    source: "lifecycle-record",
+                });
+                completed.push("dag-run-started");
+                await saveLifecycleRecord(input.repoRoot, record);
+                // runDagUseCase already runs to completion for normal path; still normalize association.
+                const located = await locateDagRun(input.repoRoot, runId);
+                if (located) {
+                    const state = await readDagRunState(located.runDir);
+                    run = toRunAssociation({
+                        runId,
+                        lifecycle: located.lifecycle,
+                        runDir: located.runDir,
+                        state,
+                    });
+                }
+                else {
+                    run = {
+                        runId,
+                        lifecycle: "completed",
+                        runDir: "",
+                        status: "status" in result ? String(result.status) : "unknown",
+                        source: "lifecycle-record",
+                    };
+                }
+                record = appendTransition(record, "dag-run-monitored");
+                completed.push("dag-run-monitored");
+                if (run.status === "finished") {
+                    record = appendTransition(record, "run-succeeded");
+                    completed.push("run-succeeded");
+                }
+                else {
+                    record = appendTransition(record, "run-failed");
+                    completed.push("run-failed");
+                }
+                await saveLifecycleRecord(input.repoRoot, record);
+            }
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            // Re-plan so promote/closeout can run in the same call after success.
+            continue;
+        }
+        if (action.type === "promote") {
+            const runId = run?.runId ?? snapshot.latestRun?.runId ?? snapshot.activeRun?.runId;
+            if (!runId) {
+                blockers.push({
+                    code: "PROMOTE_RUN_MISSING",
+                    message: "no associated run id for promotion",
+                });
+                break;
+            }
+            const promoted = await promoteRunEvidence(input.repoRoot, input.taskId, runId);
+            promotion = {
+                runId: promoted.runId,
+                modifyLogPath: promoted.modifyLogPath,
+                verifyResultPath: promoted.verifyResultPath,
+            };
+            record = appendTransition(record, "promotion-completed");
+            record = {
+                ...record,
+                promotion: {
+                    runId: promoted.runId,
+                    completedAt: new Date().toISOString(),
+                },
+            };
+            completed.push("promotion-completed");
+            await saveLifecycleRecord(input.repoRoot, record);
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+            continue;
+        }
+        if (action.type === "closeout") {
+            const closed = await closeoutTask(input.repoRoot, input.taskId);
+            closeout = { path: closed.progressPath };
+            record = appendTransition(record, "closeout-completed");
+            record = {
+                ...record,
+                closeout: {
+                    path: closed.progressPath,
+                    completedAt: new Date().toISOString(),
+                },
+            };
+            completed.push("closeout-completed");
+            await saveLifecycleRecord(input.repoRoot, record);
+            snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+        }
+    }
+    // Re-observe final snapshot
+    snapshot = await observeTaskLifecycle(input.repoRoot, input.taskId);
+    const finalGate = snapshot.lifecycleState === "awaiting-write-set-approval"
+        ? (snapshot.gate ??
+            (await buildCurrentGate(input.repoRoot, input.taskId)))
+        : snapshot.gate;
+    return {
+        taskId: input.taskId,
+        lifecycleState: snapshot.lifecycleState,
+        completedTransitions: uniqueTransitions(record.completedTransitions, completed),
+        gate: finalGate,
+        blockers: blockers.length > 0 ? blockers : snapshot.blockers,
+        warnings,
+        next: snapshot.next,
+        run,
+        promotion,
+        closeout,
+        recommendations,
+    };
+}