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

package/dist/workflows/dag/node-execution.js

@@ -0,0 +1,1081 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
+import { FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, FRONTEND_WRITER_NODE_IDS, isFrontendWriterAuthorized, readFrontendPrewriteResult, } from "./scheduler.js";
+import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
+import { resolveContextPolicy } from "./context-policy.js";
+import { buildDagNodePromptEnvelope, formatConvergenceFeedbackBlock, } from "./prompt.js";
+import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
+import { buildOutputLimitRecoverySection, loadBackendTestWriterProgressForRetry, } from "./backend-test-writer-completeness.js";
+import { computeBackoffDelayMs, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, } from "./retry-policy.js";
+import { applyNodeActivity, evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
+import { buildProtocolRetryInstruction, normalizeReviewVerdictAfterRetries, parseJsonReviewVerdict, validateOutputProtocol, } from "./output-protocol.js";
+import { getStructuredContractValidator } from "./contract-output-registry.js";
+import "./contract-validator-registrations.js";
+import { writeDagNodeJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
+import { buildProjectGovernanceContext, readCompletedWriterChangeManifests, writeProjectGovernanceContext, } from "./project-governance-context.js";
+import { assertSkillSnapshotCoversSpec, buildNodePromptFromSnapshot, isDagSkillSnapshotIntegrityError, readSkillSnapshot, } from "./skill-snapshot.js";
+import { resolveDagSkillInstructions, skillInstructionMetadata, } from "./skill-instructions.js";
+import { parseRepairArtifactFromText, resolveRepairTaskForGate, validateRepairArtifactScope, } from "./repair-artifact.js";
+import { resolveModelForTask, } from "./types.js";
+import { loadHarnessManifest } from "../../governance/harness.js";
+import { resolveExecutorThinkingMatrix } from "../../executors/model-routing.js";
+function canonicalApprovalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalApprovalJson(entry)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalApprovalJson(record[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+export function parseAndValidateFinalWriteSetApproval(input) {
+    const binding = input.task.finalWriteSetApproval;
+    if (!binding) {
+        return { ok: false, reason: "missing final write-set approval binding", approvalSourceNodeId: "(missing)" };
+    }
+    const source = input.state.nodes[binding.approvalSourceNodeId];
+    if (source?.status !== "FINISHED" || parseProcessVerdict(source) !== "pass") {
+        return {
+            ok: false,
+            reason: "final write-set approval source did not finish with VERDICT: pass",
+            approvalSourceNodeId: binding.approvalSourceNodeId,
+        };
+    }
+    const raw = canonicalNodeOutput(source);
+    const blocks = [...raw.matchAll(/```FINAL_WRITE_SET_APPROVAL_JSON\s*\r?\n([\s\S]*?)\r?\n```/g)];
+    if (blocks.length !== 1) {
+        return { ok: false, reason: `expected exactly one FINAL_WRITE_SET_APPROVAL_JSON block, found ${blocks.length}`, approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    let approval;
+    try {
+        approval = JSON.parse(blocks[0][1]);
+    }
+    catch {
+        return { ok: false, reason: "final write-set approval is not valid JSON", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const required = ["schemaVersion", "writerNodeId", "approvalSourceNodeId", "auditedPlanNodeId", "approvedWriteSet", "taskContractSha256", "auditedPlanSha256", "approvalDigest"];
+    if (Object.keys(approval).length !== required.length || required.some((key) => !(key in approval))) {
+        return { ok: false, reason: "final write-set approval has an invalid schema", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const approved = approval.approvedWriteSet;
+    if (approval.schemaVersion !== 1 ||
+        approval.writerNodeId !== binding.writerNodeId ||
+        approval.writerNodeId !== input.task.id ||
+        approval.approvalSourceNodeId !== binding.approvalSourceNodeId ||
+        approval.auditedPlanNodeId !== binding.auditedPlanNodeId ||
+        !Array.isArray(approved) ||
+        !approved.every((entry) => typeof entry === "string") ||
+        typeof approval.taskContractSha256 !== "string" ||
+        typeof approval.auditedPlanSha256 !== "string" ||
+        typeof approval.approvalDigest !== "string") {
+        return { ok: false, reason: "final write-set approval binding or field types are invalid", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    if (!/^[a-f0-9]{64}$/.test(approval.taskContractSha256) ||
+        !/^[a-f0-9]{64}$/.test(approval.auditedPlanSha256) ||
+        !/^[a-f0-9]{64}$/.test(approval.approvalDigest)) {
+        return { ok: false, reason: "final write-set approval digest fields are invalid", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const canonicalPayload = { ...approval };
+    delete canonicalPayload.approvalDigest;
+    const expectedDigest = createHash("sha256")
+        .update(canonicalApprovalJson(canonicalPayload))
+        .digest("hex");
+    if (approval.approvalDigest !== expectedDigest) {
+        return { ok: false, reason: "final write-set approval digest mismatch", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const expectedTaskDigest = input.spec.taskContractBinding?.canonicalHash;
+    const plan = input.state.nodes[binding.auditedPlanNodeId];
+    const expectedPlanDigest = createHash("sha256")
+        .update(canonicalNodeOutput(plan))
+        .digest("hex");
+    if (!expectedTaskDigest || approval.taskContractSha256 !== expectedTaskDigest || approval.auditedPlanSha256 !== expectedPlanDigest) {
+        return { ok: false, reason: "final write-set approval is stale for the task contract or audited plan", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    const effectiveWriteSet = approved;
+    if (effectiveWriteSet.length === 0 || new Set(effectiveWriteSet).size !== effectiveWriteSet.length) {
+        return { ok: false, reason: "final write-set approval must contain a non-empty ordered unique path set", approvalSourceNodeId: binding.approvalSourceNodeId };
+    }
+    for (const entry of effectiveWriteSet) {
+        const normalized = entry.replace(/\\/g, "/").replace(/^\.\//, "");
+        if (!normalized || normalized === "." || normalized === ".." || normalized.includes("*") || normalized.includes("?") || normalized.includes("REPLACE/") || normalized.includes("PLACEHOLDER")) {
+            return { ok: false, reason: `final write-set approval contains a broad or placeholder path: ${entry}`, approvalSourceNodeId: binding.approvalSourceNodeId };
+        }
+        if (!input.task.allowedPaths.some((allowed) => pathMatchesPattern(normalized, allowed))) {
+            return { ok: false, reason: `final write-set approval exceeds allowedPaths: ${entry}`, approvalSourceNodeId: binding.approvalSourceNodeId };
+        }
+        if (input.task.forbiddenPaths.some((forbidden) => pathMatchesPattern(normalized, forbidden))) {
+            return { ok: false, reason: `final write-set approval overlaps forbiddenPaths: ${entry}`, approvalSourceNodeId: binding.approvalSourceNodeId };
+        }
+    }
+    return { ok: true, effectiveWriteSet, approvalDigest: approval.approvalDigest };
+}
+export function buildNodePrompt(spec, task, upstream, options) {
+    const policy = resolveContextPolicy(spec);
+    return buildDagNodePromptEnvelope({
+        spec,
+        task,
+        upstream,
+        resolvedSkills: policy.resolveSkills(spec, task),
+        maxUpstreamChars: policy.resolveMaxUpstreamChars(task),
+        projectGovernanceContext: options?.projectGovernanceContext,
+        convergenceFeedback: options?.convergenceFeedback,
+    });
+}
+function frontendStructuredArtifactRetryGuidance(schemaId) {
+    if (schemaId === "frontend-implementation-contract-plan-patch-v1") {
+        return [
+            "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block containing only the editable RFC 7386 plan patch, immediately followed by exactly one fenced openspec-citations block.",
+            "The runtime applies your patch to its protected contract skeleton. Do not emit schemaVersion, sourceBinding, riskLevel, targets.files, or mockApi.productionDefaultOff; do not emit the full contract.",
+            "Do not emit Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
+        ];
+    }
+    if (schemaId === "frontend-implementation-contract-revision-patch-v1") {
+        return [
+            "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block containing the RFC 7386 merge-patch delta, immediately followed by exactly one fenced openspec-citations block.",
+            "The delta contains only the fields you change; null deletes a key, arrays and scalars replace, and plain objects merge recursively. Do not emit a full contract or a schemaVersion/targets section.",
+            "Do not emit Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
+        ];
+    }
+    return [
+        "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block conforming to frontend-implementation-contract-v1, immediately followed by exactly one fenced openspec-citations block.",
+        "The contract JSON fields are the complete implementation plan. Do not emit a separate plan document, Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
+    ];
+}
+function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics) {
+    if (attemptNumber <= 1)
+        return basePrompt;
+    if (previousFailureCategory === "protocol-invalid" &&
+        task.outputProtocol &&
+        previousProtocolReason) {
+        return [
+            basePrompt,
+            "",
+            buildProtocolRetryInstruction(task.outputProtocol, previousProtocolReason),
+        ].join("\n");
+    }
+    if (previousFailureCategory === "invalid-output" &&
+        task.structuredContractOutput &&
+        previousProtocolReason) {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt produced an invalid frontend implementation contract:",
+            previousProtocolReason,
+            ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+            "Fix every reported field violation: do not emit null for optional fields, do not misspell field names, and match the required types exactly.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "structured-output-truncated" &&
+        task.structuredContractOutput) {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt was truncated by the provider (stopReason=length) before the JSON contract was completed.",
+            ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+            "The JSON artifact must be complete; omit evidence excerpts and duplicated upstream context.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "writer-empty-diff") {
+        const maxAttempts = task.retryPolicy?.maxAttempts ?? 3;
+        // When a completeness progress exists for this writer, fold the concrete
+        // target paths into the empty-diff retry so the model does not guess and
+        // does not need to read a forbidden `.harness/**` evidence file.
+        if (recoveryTargetPaths && recoveryTargetPaths.length > 0) {
+            return [
+                basePrompt,
+                "",
+                buildOutputLimitRecoverySection({
+                    attempt: attemptNumber,
+                    maxAttempts,
+                    reason: "T4",
+                    targetPaths: recoveryTargetPaths,
+                    diagnostics: recoveryDiagnostics,
+                }),
+            ].join("\n");
+        }
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt made no file changes.",
+            "Use write/edit tools immediately to create the required bounded files; do not repeat analysis or planning.",
+            "Return only after producing a non-empty bounded diff and the required implementation outcome.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "incomplete-write-set") {
+        const maxAttempts = task.retryPolicy?.maxAttempts ?? 3;
+        // Embed concrete missing/broken paths from the run-owned progress facts
+        // so the continuation attempt is fully self-contained and never reads
+        // a forbidden `.harness/**` evidence file. When the loader finds no
+        // progress facts yet (rare), fall back to the path-pointing contract.
+        if (recoveryTargetPaths) {
+            return [
+                basePrompt,
+                "",
+                buildOutputLimitRecoverySection({
+                    attempt: attemptNumber,
+                    maxAttempts,
+                    reason: "T3_or_T5",
+                    targetPaths: recoveryTargetPaths,
+                    diagnostics: recoveryDiagnostics,
+                }),
+            ].join("\n");
+        }
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            `OUTPUT_LIMIT_RECOVERY attempt=${attemptNumber}/${maxAttempts}`,
+            "reason=T3_or_T5",
+            "Previous attempt produced an incomplete or structurally broken write set (Completeness Gate).",
+            "Continue or repair ONLY missing/broken target paths listed in reports/backend-test-output-limit-recovery.md and contracts/backend-test-writer-progress-*.json when present.",
+            "One file per write/edit; no chat dump of full bodies; do not delete or shrink in-scope cases/rules/TPs.",
+            "Prefer edit/append for truncated files; rewrite a file only if unparseable or empty.",
+            "After targets are complete, short IMPLEMENTATION_OUTCOME only.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory !== "output-too-large") {
+        return basePrompt;
+    }
+    if (task.outputMode === "structured-required") {
+        if (task.structuredContractOutput) {
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "Previous attempt exceeded the structured output size limit.",
+                ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+                "Keep every required field but make values concise; omit evidence excerpts and duplicated upstream context.",
+                "</retry_instruction>",
+            ].join("\n");
+        }
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt exceeded the structured output size limit.",
+            "Return only the compact structured artifact required by this node's output contract.",
+            "Do not include explanatory prose, duplicated upstream context, long evidence excerpts, or additional markdown sections.",
+            "If a fenced JSON object is required, output exactly one fenced json block and nothing else.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    return [
+        basePrompt,
+        "",
+        "<retry_instruction>",
+        "Previous attempt exceeded the output size limit.",
+        "Return a minimal plan: ordered steps, narrow writeSet boundaries, and verification commands.",
+        "Drop verbatim upstream quotes, long evidence excerpts, and repeated context.",
+        "</retry_instruction>",
+    ].join("\n");
+}
+export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd, options) {
+    const policy = resolveContextPolicy(spec);
+    const skillNames = policy.resolveSkills(spec, task);
+    const budget = policy.resolveSkillInstructionBudget(task);
+    const resolvedSkillInstructions = task.executor === "pi"
+        ? await resolveDagSkillInstructions(skillNames, {
+            cwd,
+            includeLearnedPatterns: budget.includeLearnedPatterns,
+            perSkillMaxChars: budget.perSkillMaxChars,
+            totalMaxChars: budget.totalMaxChars,
+        })
+        : [];
+    return {
+        prompt: buildDagNodePromptEnvelope({
+            spec,
+            task,
+            upstream,
+            resolvedSkills: skillNames,
+            resolvedSkillInstructions,
+            maxUpstreamChars: policy.resolveMaxUpstreamChars(task),
+            projectGovernanceContext: options?.projectGovernanceContext,
+            convergenceFeedback: options?.convergenceFeedback,
+        }),
+        resolvedSkills: skillInstructionMetadata(resolvedSkillInstructions),
+    };
+}
+export function canonicalNodeOutput(node) {
+    const assistantText = node?.assistantText ?? "";
+    return assistantText.trim().length > 0 ? assistantText : (node?.stdout ?? "");
+}
+export function parseProcessVerdict(node) {
+    const text = canonicalNodeOutput(node);
+    const jsonVerdict = parseJsonReviewVerdict(text);
+    if (jsonVerdict.ok)
+        return jsonVerdict.verdict;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "VERDICT: pass")
+            return "pass";
+        if (trimmed === "VERDICT: request-revision")
+            return "request-revision";
+    }
+    return "unknown";
+}
+/**
+ * Derive a bounded convergence feedback block for the next-round
+ * supervisor/repair node from `state.convergence`. Deterministic: reads the
+ * last passHistory entry and its preservedNodeRecordPath pointers; never
+ * searches the run directory. Returns undefined on pass 1 (no prior evidence).
+ */
+export function deriveConvergenceFeedback(state) {
+    const convergence = state.convergence;
+    if (!convergence?.enabled || convergence.currentPass <= 1)
+        return undefined;
+    const last = convergence.passHistory.at(-1);
+    if (!last)
+        return undefined;
+    return {
+        pass: last.pass,
+        reason: last.reason,
+        hardVerifyFailureCategory: last.hardVerifyFailureCategory,
+        processVerdict: last.processVerdict,
+        reviewVerdict: last.reviewVerdict,
+        reviewFailureCategory: last.reviewFailureCategory,
+        shellSuccessCount: last.shellSuccessCount,
+        repairArtifact: last.repairArtifact
+            ? {
+                failureClass: last.repairArtifact.failureClass,
+                rootCause: last.repairArtifact.rootCause,
+                fixScope: last.repairArtifact.fixScope,
+                invariant: last.repairArtifact.invariant,
+            }
+            : undefined,
+        evidenceRefs: last.artifactRefs.map((ref) => ({
+            nodeId: ref.nodeId,
+            preservedNodeRecordPath: ref.preservedNodeRecordPath,
+        })),
+    };
+}
+function assertRepairArtifactVerdictMatchesSupervisor(input) {
+    const supervisorVerdict = parseProcessVerdict(input.node);
+    if (supervisorVerdict === "unknown")
+        return;
+    if (supervisorVerdict !== input.artifactVerdict) {
+        throw new Error(`repair artifact gate failed: verdict mismatch between supervisor ${supervisorVerdict} and REPAIR_ARTIFACT_JSON ${input.artifactVerdict}`);
+    }
+}
+function parseSupervisorRepairArtifact(node) {
+    return parseRepairArtifactFromText(canonicalNodeOutput(node));
+}
+function validateRepairArtifactGateBeforeShell(input) {
+    const gate = input.task.shell?.repairArtifactGate;
+    if (!gate)
+        return;
+    const upstream = input.state.nodes[gate.fromNodeId];
+    const parsed = parseSupervisorRepairArtifact(upstream);
+    if (!parsed.ok) {
+        throw new Error(`repair artifact gate failed: ${parsed.reason}`);
+    }
+    assertRepairArtifactVerdictMatchesSupervisor({
+        node: upstream,
+        artifactVerdict: parsed.artifact.verdict,
+    });
+    upstream.repairArtifact = parsed.artifact;
+    const resolution = resolveRepairTaskForGate({
+        tasks: Array.from(input.tasksById.values()),
+        gateTask: input.task,
+    });
+    if (!resolution.ok) {
+        // A pass verdict does not need a repair writer; only fail closed when the
+        // supervisor requested a revision that must be routed to a repair node.
+        if (parsed.artifact.verdict === "request-revision") {
+            throw new Error(`repair artifact gate failed: ${resolution.reason}`);
+        }
+        return;
+    }
+    const scoped = validateRepairArtifactScope({
+        artifact: parsed.artifact,
+        repairTask: resolution.repairTask,
+    });
+    if (!scoped.ok) {
+        throw new Error(`repair artifact gate failed: ${scoped.reason}`);
+    }
+}
+function recordRepairArtifactForSupervisorNode(input) {
+    const dependentGate = Object.values(input.state.nodes).find((record) => record.id === "process-gate-shell");
+    if (input.task.id !== "process-supervisor-pi" || !dependentGate)
+        return;
+    const parsed = parseSupervisorRepairArtifact(input.node);
+    if (parsed.ok) {
+        input.node.repairArtifact = parsed.artifact;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function durationBetween(startedAt, finishedAt) {
+    const started = startedAt ? new Date(startedAt).getTime() : Number.NaN;
+    const finished = finishedAt ? new Date(finishedAt).getTime() : Number.NaN;
+    return Number.isFinite(started) && Number.isFinite(finished)
+        ? Math.max(0, finished - started)
+        : 0;
+}
+function sumAttemptMetric(attempts, select) {
+    const values = attempts.map(select).filter((value) => value !== undefined);
+    return values.length > 0
+        ? values.reduce((sum, value) => sum + value, 0)
+        : undefined;
+}
+async function notifyNodeObserver(observer, event, nodeId, state, chunk) {
+    try {
+        if (event === "onNodeOutput") {
+            await observer?.onNodeOutput?.(nodeId, chunk ?? "", state);
+            return;
+        }
+        await observer?.[event]?.(nodeId, state);
+    }
+    catch {
+        // Observers are derived views; they must not affect canonical DAG execution.
+    }
+}
+export async function executeDagNode(input) {
+    const { nodeId, tasksById, state, spec, cwd, runDir, executeNode } = input;
+    let task = tasksById.get(nodeId);
+    const node = state.nodes[nodeId];
+    const failBeforePrompt = async (error, failureCategory) => {
+        const failedAt = new Date().toISOString();
+        node.startedAt ??= failedAt;
+        node.status = "ERROR";
+        node.stderr = error instanceof Error ? error.message : String(error);
+        node.failureCategory = failureCategory;
+        node.finishedAt = failedAt;
+        node.lastActivityAt = node.finishedAt;
+        node.durationMs = durationBetween(node.startedAt, node.finishedAt);
+        node.timing = { retryBackoffMs: 0, settlementCleanupMs: 0 };
+        state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+        await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+        await input.persistState();
+        await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+    };
+    const failSkillSnapshot = (error) => failBeforePrompt(error, "skill-snapshot-integrity");
+    const skipFrontendWriter = async (admission) => {
+        const skippedAt = new Date().toISOString();
+        node.startedAt ??= skippedAt;
+        node.frontendWriterAdmission = admission;
+        node.status = "SKIPPED";
+        node.skippedReason = "frontend-prewrite-not-authorized";
+        node.finishedAt = skippedAt;
+        node.lastActivityAt = skippedAt;
+        node.durationMs = durationBetween(node.startedAt, node.finishedAt);
+        node.timing = { retryBackoffMs: 0, settlementCleanupMs: 0 };
+        state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+        await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+        await input.persistState();
+        await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+    };
+    if (task.finalWriteSetApproval) {
+        const authorization = parseAndValidateFinalWriteSetApproval({ task, spec, state });
+        if (!authorization.ok) {
+            node.runtimeWriteAuthorization = {
+                schemaVersion: 1,
+                status: "rejected",
+                approvalSourceNodeId: authorization.approvalSourceNodeId,
+                reason: authorization.reason,
+            };
+            await failBeforePrompt(new Error(`final-write-set-approval-invalid: ${authorization.reason}`), "final-write-set-approval-invalid");
+            return;
+        }
+        task = {
+            ...task,
+            writeSet: authorization.effectiveWriteSet,
+            resolvedFinalWriteSetApproval: {
+                approvalDigest: authorization.approvalDigest,
+                approvalSourceNodeId: task.finalWriteSetApproval.approvalSourceNodeId,
+            },
+        };
+        node.runtimeWriteAuthorization = {
+            schemaVersion: 1,
+            status: "validated",
+            approvalSourceNodeId: task.finalWriteSetApproval.approvalSourceNodeId,
+            approvalDigest: authorization.approvalDigest,
+            effectiveWriteSet: [...authorization.effectiveWriteSet],
+        };
+    }
+    if (FRONTEND_WRITER_NODE_IDS.includes(nodeId)) {
+        const admission = await readFrontendPrewriteResult(runDir);
+        if (!admission.ok) {
+            await skipFrontendWriter(undefined);
+            return;
+        }
+        const decision = isFrontendWriterAuthorized(admission.result);
+        const record = {
+            schemaVersion: 1,
+            writerNodeId: nodeId,
+            decision,
+            sourceArtifact: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
+            artifactHash: admission.artifactHash,
+            checkedAt: new Date().toISOString(),
+            reason: decision === "denied"
+                ? `classification: ${admission.result.classification}`
+                : null,
+        };
+        if (decision === "denied") {
+            await skipFrontendWriter(record);
+            return;
+        }
+        node.frontendWriterAdmission = record;
+    }
+    let projectGovernanceContext;
+    if (task.governanceStandardReview) {
+        try {
+            const changeManifest = await readCompletedWriterChangeManifests({
+                runDir,
+                spec,
+                state,
+            });
+            projectGovernanceContext = await buildProjectGovernanceContext({
+                runId: state.runId,
+                cwd,
+                changeManifest,
+                runDir,
+            });
+            state.projectGovernanceContextRef = await writeProjectGovernanceContext(runDir, projectGovernanceContext);
+            await input.persistState();
+        }
+        catch (error) {
+            await failBeforePrompt(error, "project-governance-integrity");
+            return;
+        }
+    }
+    const isDynamicTask = Boolean(task.dynamicExpansion ||
+        task.dynamicReduction ||
+        task.dynamicCondition ||
+        task.dynamicLoopUntil);
+    let snapshotPrompt;
+    if (state.skillSnapshotRef) {
+        try {
+            const skillSnapshot = await readSkillSnapshot(runDir, state.skillSnapshotRef, {
+                expectedRunId: state.runId,
+            });
+            assertSkillSnapshotCoversSpec(skillSnapshot, spec, state);
+            if (!isDynamicTask) {
+                snapshotPrompt = buildNodePromptFromSnapshot({
+                    spec,
+                    task,
+                    upstream: state.nodes,
+                    snapshot: skillSnapshot,
+                    projectGovernanceContext,
+                });
+                const feedbackBlock = formatConvergenceFeedbackBlock(deriveConvergenceFeedback(state));
+                if (feedbackBlock &&
+                    (task.role === "supervisor" ||
+                        task.role === "implementer" ||
+                        task.id === "process-supervisor-pi" ||
+                        task.id === "repair-pi")) {
+                    snapshotPrompt = {
+                        ...snapshotPrompt,
+                        prompt: `${snapshotPrompt.prompt}\n\n<convergence_feedback>\n${feedbackBlock}\n</convergence_feedback>`,
+                    };
+                }
+            }
+        }
+        catch (error) {
+            await failSkillSnapshot(error);
+            return;
+        }
+    }
+    node.status = "RUNNING";
+    node.startedAt = new Date().toISOString();
+    node.lastActivityAt = node.startedAt;
+    node.lastMeaningfulProgressAt = node.startedAt;
+    node.livenessStatus = "active";
+    node.currentAttempt = 1;
+    if (task.shell?.verifyEvidence) {
+        node.verifyEvidence = task.shell.verifyEvidence;
+    }
+    await input.persistState();
+    await notifyNodeObserver(input.observer, "onNodeStart", nodeId, state);
+    if (isDynamicTask) {
+        const dynamicExecutionStartedAt = new Date().toISOString();
+        try {
+            const result = await input.executeDynamicNode({
+                task,
+                tasksById,
+                state,
+                spec,
+                cwd,
+                runDir,
+                executeNode,
+                observer: input.observer,
+                persistState: input.persistState,
+            });
+            node.stdout = result.stdout;
+            node.stderr = result.stderr;
+            node.failureCategory = result.failureCategory;
+            node.status = result.ok ? "FINISHED" : "ERROR";
+        }
+        catch (error) {
+            node.status = "ERROR";
+            node.stderr = error instanceof Error ? error.message : String(error);
+        }
+        const dynamicExecutionFinishedAt = new Date().toISOString();
+        const dynamicExecutionWallDurationMs = durationBetween(dynamicExecutionStartedAt, dynamicExecutionFinishedAt);
+        if (node.status === "FINISHED") {
+            const artifactMeta = await persistLongNodeOutputArtifacts({
+                runDir,
+                nodeId,
+                stdout: node.stdout,
+                assistantText: node.assistantText,
+            });
+            Object.assign(node, artifactMeta);
+        }
+        const dynamicFinishedAt = new Date().toISOString();
+        node.finishedAt = dynamicFinishedAt;
+        node.lastActivityAt = dynamicFinishedAt;
+        node.durationMs = durationBetween(node.startedAt, dynamicFinishedAt);
+        node.timing = {
+            retryBackoffMs: 0,
+            settlementCleanupMs: Math.max(0, node.durationMs - dynamicExecutionWallDurationMs),
+        };
+        state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+        await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+        await input.persistState();
+        await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+        return;
+    }
+    let prompt;
+    let resolvedSkills;
+    try {
+        if (snapshotPrompt) {
+            prompt = snapshotPrompt.prompt;
+            resolvedSkills = snapshotPrompt.resolvedSkills;
+        }
+        else {
+            ({ prompt, resolvedSkills } =
+                await buildNodePromptWithResolvedSkillInstructions(spec, task, state.nodes, cwd, {
+                    projectGovernanceContext,
+                    convergenceFeedback: deriveConvergenceFeedback(state),
+                }));
+        }
+    }
+    catch (error) {
+        if (!isDagSkillSnapshotIntegrityError(error))
+            throw error;
+        await failSkillSnapshot(error);
+        return;
+    }
+    node.resolvedSkills = resolvedSkills;
+    await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
+    const model = resolveModelForTask(task, spec.executorModels);
+    let thinking;
+    if (task.executor === "pi") {
+        try {
+            const manifest = await loadHarnessManifest(cwd);
+            thinking = resolveExecutorThinkingMatrix(manifest.executors?.pi)[task.complexity];
+        }
+        catch {
+            // Invalid or missing harness preserves the previous no-override behavior.
+        }
+    }
+    const retryPolicy = task.retryPolicy &&
+        (isSafeReadOnlyPiRetryCandidate(task) ||
+            isWriterEmptyDiffRetryCandidate(task) ||
+            isWriterTransportRetryCandidate(task))
+        ? task.retryPolicy
+        : undefined;
+    const maxAttempts = retryPolicy?.maxAttempts ?? 1;
+    const attempts = [];
+    let totalAttemptWallDurationMs = 0;
+    let totalBackoffMs = 0;
+    const livenessPolicy = resolveLivenessPolicy(spec.defaults?.livenessPolicy, task.livenessPolicy);
+    /**
+     * Attempt-fenced, throttled activity sink. Late events from a previous
+     * attempt are no-ops. Persistence is best-effort and never throws to the
+     * executor path.
+     */
+    const ACTIVITY_PERSIST_MIN_INTERVAL_MS = 2_000;
+    let lastActivityPersistMs = 0;
+    const reportActivity = (activity) => {
+        const accepted = applyNodeActivity({
+            node,
+            currentAttempt: node.currentAttempt ?? 1,
+            activityAttempt: activity.attempt,
+            kind: activity.kind,
+            at: activity.at,
+        });
+        if (!accepted)
+            return;
+        const evaluation = evaluateNodeLiveness({
+            node,
+            policy: livenessPolicy,
+            runnerHeartbeatAt: state.runner?.heartbeatAt,
+        });
+        node.livenessStatus = evaluation.status;
+        const nowMs = Date.now();
+        if (nowMs - lastActivityPersistMs < ACTIVITY_PERSIST_MIN_INTERVAL_MS) {
+            return;
+        }
+        lastActivityPersistMs = nowMs;
+        // Canonical mid-call activity lives in active state.json. Queue through the
+        // runner's serialized state writer; per-node records remain terminal/attempt
+        // evidence so a late best-effort write cannot recreate an archived run dir.
+        void input.persistState().catch(() => { });
+    };
+    let terminalResult;
+    let previousFailureCategory;
+    let previousProtocolReason;
+    for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
+        const attemptStartedAt = new Date().toISOString();
+        node.currentAttempt = attemptNumber;
+        node.livenessStatus = "active";
+        let result;
+        try {
+            validateRepairArtifactGateBeforeShell({
+                task,
+                tasksById,
+                state,
+            });
+            // For backend-test generation writers, load the most recent
+            // completeness progress from the run dir so the next attempt's
+            // prompt embeds concrete target paths. Undefined for non-writers
+            // or when no progress facts exist yet (no-op).
+            const recoveryProgress = await loadBackendTestWriterProgressForRetry(runDir, task.id);
+            const recoveryTargetPaths = recoveryProgress?.targetPaths;
+            // Fold per-path structural reasons (e.g. T5 "case heading at wrong
+            // level") into the retry prompt so the model fixes the exact defect
+            // instead of guessing from a generic hint.
+            const recoveryDiagnostics = recoveryProgress?.issues
+                ?.filter((i) => !!i.path && i.recoverable)
+                .reduce((acc, i) => {
+                (acc[i.path] ??= []).push(i.detail);
+                return acc;
+            }, {});
+            result = await executeNode({
+                task,
+                cwd,
+                model,
+                ...(thinking ? { thinking } : {}),
+                prompt: buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics),
+                attempt: attemptNumber,
+                reportActivity,
+                timeoutMs: livenessPolicy.absoluteMaxWallClockMs,
+                stallTimeoutMs: livenessPolicy.stallProbeMs,
+                abortGraceMs: livenessPolicy.abortGraceMs,
+            });
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error),
+                durationMs: 0,
+            };
+        }
+        // R0: executor ok=true still fails closed when outputProtocol is violated.
+        // Valid semantic results (e.g. VERDICT: request-revision) pass validation.
+        if (result.ok && task.outputProtocol) {
+            const protocolText = canonicalNodeOutput(result);
+            const protocolCheck = validateOutputProtocol(task.outputProtocol, protocolText);
+            if (!protocolCheck.ok) {
+                result = {
+                    ...result,
+                    ok: false,
+                    failureCategory: protocolCheck.failureCategory,
+                    stderr: [result.stderr, protocolCheck.reason]
+                        .filter(Boolean)
+                        .join("\n"),
+                };
+                previousProtocolReason = protocolCheck.reason;
+            }
+            else {
+                previousProtocolReason = undefined;
+            }
+        }
+        // R1: structured contract nodes self-validate their output so schema,
+        // typo, and null violations surface as retryable invalid-output at the
+        // producing node instead of failing the whole run at the prewrite gate.
+        if (result.ok && task.structuredContractOutput) {
+            const validator = getStructuredContractValidator(task.structuredContractOutput.schemaId);
+            if (validator) {
+                const contractText = canonicalNodeOutput(result);
+                const contractCheck = await validator({
+                    runDir,
+                    text: contractText,
+                    sourceBinding: spec.sourceBinding,
+                    nodeId,
+                    attempt: attemptNumber,
+                    structuredContractOutput: task.structuredContractOutput,
+                });
+                if (!contractCheck.ok) {
+                    // A provider stopReason=length means the response was cut before the
+                    // JSON contract could complete; separate it from an ordinary bad
+                    // contract so the retry switches to a JSON-only output strategy.
+                    const attemptStopReason = result.stopReason;
+                    result = {
+                        ...result,
+                        ok: false,
+                        failureCategory: attemptStopReason === "length"
+                            ? "structured-output-truncated"
+                            : "invalid-output",
+                        stderr: [result.stderr, contractCheck.reason]
+                            .filter(Boolean)
+                            .join("\n"),
+                    };
+                    previousProtocolReason = contractCheck.reason;
+                }
+                else {
+                    if (contractCheck.normalizedText) {
+                        result = {
+                            ...result,
+                            assistantText: contractCheck.normalizedText,
+                            stdout: contractCheck.normalizedText,
+                        };
+                    }
+                    previousProtocolReason = undefined;
+                }
+            }
+            else {
+                // DAG spec validation rejects unknown schemaIds; this is a
+                // defensive fallback for a registry that has not been populated.
+                console.warn(`[run-dag] warning: no structured contract validator registered for schemaId ${task.structuredContractOutput.schemaId}; skipping node self-check`);
+            }
+        }
+        const attemptFinishedAt = new Date().toISOString();
+        const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
+        totalAttemptWallDurationMs += attemptWallDurationMs;
+        const attemptRecord = {
+            attempt: attemptNumber,
+            startedAt: attemptStartedAt,
+            finishedAt: attemptFinishedAt,
+            durationMs: attemptWallDurationMs,
+            timing: { executorDurationMs: result.durationMs },
+            ok: result.ok,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            assistantText: result.assistantText,
+            failureCategory: result.failureCategory,
+            backend: result.backend,
+            sdkAttempted: result.sdkAttempted,
+            tokensUsed: result.tokensUsed,
+            parsedEvents: result.parsedEvents,
+            artifactPath: `${nodeId}/attempt-${attemptNumber}.json`,
+        };
+        if (retryPolicy !== undefined) {
+            attempts.push(attemptRecord);
+            // Persist immutable attempt evidence BEFORE waiting for the next attempt
+            // and before applying the result to the node record, so a later success
+            // never overwrites prior failure evidence.
+            await writeDagNodeJsonArtifact(runDir, nodeId, `attempt-${attemptNumber}.json`, attemptRecord);
+            node.attempts = attempts;
+        }
+        // Reflect the latest attempt on the node so progress is observable,
+        // but keep node.status RUNNING while retry is still possible.
+        node.durationMs = durationBetween(node.startedAt, attemptFinishedAt);
+        node.stdout = result.stdout;
+        node.stderr = result.stderr;
+        node.failureCategory = result.failureCategory;
+        node.assistantText = result.assistantText;
+        node.backend = result.backend;
+        node.sdkAttempted = result.sdkAttempted;
+        node.tokensUsed =
+            retryPolicy === undefined
+                ? result.tokensUsed
+                : sumAttemptMetric(attempts, (attempt) => attempt.tokensUsed);
+        node.parsedEvents =
+            retryPolicy === undefined
+                ? result.parsedEvents
+                : sumAttemptMetric(attempts, (attempt) => attempt.parsedEvents);
+        node.lastActivityAt = attemptFinishedAt;
+        if (result.failureCategory === "termination-unconfirmed") {
+            node.needsAttentionReason = "attempt-termination-unconfirmed";
+            node.livenessStatus = "needs-attention";
+        }
+        if (retryPolicy !== undefined) {
+            state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+            await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+            await input.persistState();
+        }
+        terminalResult = result;
+        previousFailureCategory = result.failureCategory;
+        if (result.ok)
+            break;
+        const canRetry = retryPolicy !== undefined && attemptNumber < maxAttempts;
+        const retryable = retryPolicy !== undefined &&
+            (isRetryablePiFailureCategory(result.failureCategory, {
+                retryCategories: retryPolicy.retryCategories,
+            }) ||
+                (result.failureCategory === "protocol-invalid" &&
+                    task.outputProtocol?.retryOnInvalid === true));
+        if (!canRetry || !retryable)
+            break;
+        const delayMs = computeBackoffDelayMs(attemptNumber + 1, retryPolicy);
+        if (delayMs > 0) {
+            const backoffStartedAt = new Date().toISOString();
+            await sleep(delayMs);
+            const backoffFinishedAt = new Date().toISOString();
+            totalBackoffMs += durationBetween(backoffStartedAt, backoffFinishedAt);
+            // Keep lastActivityAt fresh so backoff wait is not misread as node-quiet.
+            node.lastActivityAt = new Date().toISOString();
+            state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+            await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+            await input.persistState();
+        }
+    }
+    // AC2: after retries are exhausted on a canonical review verdict protocol
+    // node, attempt one deterministic normalization of the full terminal output.
+    // This ONLY re-wraps output so the first non-empty line is the single
+    // supported verdict; it never changes the verdict value, and missing /
+    // duplicated / conflicting / illegal verdicts remain protocol-invalid.
+    // Shell, write-guard, timeout, and model failures are never normalized.
+    if (terminalResult &&
+        !terminalResult.ok &&
+        terminalResult.failureCategory === "protocol-invalid" &&
+        task.outputProtocol) {
+        const fullText = terminalResult.assistantText &&
+            terminalResult.assistantText.trim().length > 0
+            ? terminalResult.assistantText
+            : (terminalResult.stdout ?? "");
+        const normalized = normalizeReviewVerdictAfterRetries(task.outputProtocol, fullText);
+        if (normalized.ok) {
+            const normalizedText = normalized.normalizedOutput;
+            terminalResult = {
+                ...terminalResult,
+                ok: true,
+                failureCategory: undefined,
+                assistantText: normalizedText,
+                stdout: normalizedText,
+                stderr: [
+                    terminalResult.stderr,
+                    `verdict normalized after retries exhausted: ${normalized.verdictLine}`,
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+            };
+            // Sync the observable node fields so downstream gates and reports see the
+            // normalized first-line verdict while the original evidence is preserved.
+            node.assistantText = normalizedText;
+            node.stdout = normalizedText;
+            node.failureCategory = undefined;
+            node.stderr = terminalResult.stderr;
+        }
+    }
+    const result = terminalResult;
+    try {
+        recordRepairArtifactForSupervisorNode({
+            task,
+            node,
+            state,
+        });
+        const outputChunk = result.assistantText ?? result.stdout;
+        if (outputChunk.trim()) {
+            await notifyNodeObserver(input.observer, "onNodeOutput", nodeId, state, outputChunk);
+        }
+        node.status = result.ok ? "FINISHED" : "ERROR";
+        if (result.ok) {
+            const decisionRecord = await recordDecisionEnvelopeForNode({
+                task,
+                runDir,
+                nodeId,
+                assistantText: node.assistantText ?? result.assistantText,
+            });
+            if (decisionRecord) {
+                node.decisionEnvelope = decisionRecord.nodeRecord;
+                if (!decisionRecord.nodeRecord.parseOk) {
+                    node.status = "ERROR";
+                    node.failureCategory = "decision-envelope-invalid";
+                    node.stderr = [
+                        node.stderr,
+                        ...(decisionRecord.nodeRecord.errors ?? []),
+                    ]
+                        .filter(Boolean)
+                        .join("\n");
+                }
+                else if (shouldPauseOnHumanEscalation(task, decisionRecord.nodeRecord) &&
+                    decisionRecord.envelope) {
+                    const pausedAt = new Date().toISOString();
+                    const nodeArtifactsDir = path.join(runDir, nodeId);
+                    const { jsonPath } = await writeHumanEscalationArtifacts({
+                        nodeArtifactsDir,
+                        runId: state.runId,
+                        nodeId,
+                        envelope: decisionRecord.envelope,
+                        pausedAt,
+                    });
+                    node.pauseReason = "decision-gate-requires-human";
+                    node.escalationArtifactPath = jsonPath;
+                    input.onPause(nodeId, pausedAt, node.pauseReason);
+                }
+            }
+        }
+    }
+    catch (error) {
+        node.status = "ERROR";
+        node.stderr = error instanceof Error ? error.message : String(error);
+    }
+    // Attempt artifacts must observe their own persisted boundaries before the
+    // potentially asynchronous artifact write; post-attempt work belongs to node timing.
+    const terminalFinishedAt = new Date().toISOString();
+    node.finishedAt = terminalFinishedAt;
+    node.lastActivityAt = terminalFinishedAt;
+    node.durationMs = durationBetween(node.startedAt, terminalFinishedAt);
+    node.timing = {
+        retryBackoffMs: totalBackoffMs,
+        settlementCleanupMs: Math.max(0, durationBetween(node.startedAt, terminalFinishedAt) -
+            totalAttemptWallDurationMs -
+            totalBackoffMs),
+    };
+    if (node.status === "FINISHED") {
+        const artifactMeta = await persistLongNodeOutputArtifacts({
+            runDir,
+            nodeId,
+            stdout: node.stdout,
+            assistantText: node.assistantText,
+        });
+        Object.assign(node, artifactMeta);
+        if (task.shell?.jsonArtifactGate) {
+            const artifactPath = path.join(runDir, task.shell.jsonArtifactGate.outputDir, task.shell.jsonArtifactGate.artifactName);
+            const bytes = await readFile(artifactPath);
+            node.structuredArtifactPath = artifactPath;
+            node.structuredArtifactSha256 = createHash("sha256")
+                .update(bytes)
+                .digest("hex");
+            node.structuredArtifactSchemaId = task.shell.jsonArtifactGate.schemaId;
+        }
+        else if (task.shell?.backendTestPipeline === "classification-result-context" ||
+            task.shell?.backendTestPipeline === "markdown-execute-html") {
+            // Legacy 15-node and Markdown-first 8-node pipelines materialize
+            // contracts/backend-test-result.json without jsonArtifactGate. Bind it
+            // so Outcome adapters project kind=backend-test-result for Ready Planner.
+            const artifactPath = path.join(runDir, "contracts", "backend-test-result.json");
+            if (existsSync(artifactPath)) {
+                const bytes = await readFile(artifactPath);
+                node.structuredArtifactPath = artifactPath;
+                node.structuredArtifactSha256 = createHash("sha256")
+                    .update(bytes)
+                    .digest("hex");
+                node.structuredArtifactSchemaId = "backend-test-result-v1";
+            }
+        }
+    }
+    const finishedAt = new Date().toISOString();
+    node.finishedAt = finishedAt;
+    node.lastActivityAt = finishedAt;
+    node.durationMs = durationBetween(node.startedAt, finishedAt);
+    node.timing = {
+        ...node.timing,
+        settlementCleanupMs: Math.max(0, durationBetween(node.startedAt, finishedAt) -
+            totalAttemptWallDurationMs -
+            totalBackoffMs),
+    };
+    state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+    await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+    await input.persistState();
+    await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+}