@tea-agent/loop-agent 0.11.0 → 0.12.0

package/dist/workflows/dag/init-hybrid.js

@@ -2,9 +2,10 @@ import { access, readdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { assertValidDagSpec } from "./validate.js";
-import { DEFAULT_DAG_OUTPUT_LANGUAGE, DEFAULT_DAG_EXECUTOR_MODELS, parseDagSpec, } from "./types.js";
+import { DAG_AGENT_RUNTIME_PI_ONLY, DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1, DAG_RUNTIME_CONTRACT_SCHEMA_VERSION, DEFAULT_DAG_OUTPUT_LANGUAGE, DEFAULT_DAG_EXECUTOR_MODELS, parseDagSpec, } from "./types.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { BASELINE_FORBIDDEN_PATHS } from "./governance-constants.js";
+import { DEFAULT_READ_ONLY_PI_RETRY_POLICY, isSafeReadOnlyPiRetryCandidate } from "./retry-policy.js";
 import { resolveAdapter } from "../../adapters/index.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
 import { buildAuthoritySurfaceAuditNode, buildAuthoritySurfaceGateNode, resolveAuthoritySurfaceAudit, } from "./authority-surface.js";
@@ -77,6 +78,18 @@ const FRONTEND_DESIGN_REVIEW_SKILLS = ["frontend-design-review"];
 const FRONTEND_REVIEW_SKILLS = ["frontend-review"];
 const FRONTEND_VERIFICATION_SKILLS = ["frontend-verification"];
 const IMPLEMENT_WRITESET_PLACEHOLDER = "REPLACE/WITH/NARROW/IMPLEMENT/PATHS/**";
+/**
+ * Runtime contract stamped on every newly generated DAG. Capability fields are
+ * authoritative and are the primary compatibility gate. `minimumControllerVersion`
+ * is intentionally omitted here: it is an optional diagnostic hint, and hardcoding
+ * a future version would make a controller reject the very DAGs it generates.
+ * Operators can still pin a minimum version on hand-authored specs when needed.
+ */
+export const GENERATED_DAG_RUNTIME_CONTRACT = {
+    schemaVersion: DAG_RUNTIME_CONTRACT_SCHEMA_VERSION,
+    agentRuntime: DAG_AGENT_RUNTIME_PI_ONLY,
+    repairWriterProtocol: DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1,
+};
 function resolveEnabledExecutors(manifestExecutors) {
     return Object.entries(manifestExecutors)
         .filter(([, config]) => config.enabled !== false)
@@ -605,8 +618,9 @@ export function buildStandardHybridDagFromTask(sources) {
         ...STANDARD_GLOBAL_CONSTRAINTS,
     ];
     const spec = {
-        version: 2,
+        version: 3,
         title: `Hybrid DAG: ${taskConfig.title}`,
+        runtimeContract: GENERATED_DAG_RUNTIME_CONTRACT,
         outputLanguage: sources.outputLanguage ?? DEFAULT_DAG_OUTPUT_LANGUAGE,
         objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
         successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
@@ -739,6 +753,7 @@ export function buildStandardHybridDagFromTask(sources) {
         ],
     };
     applySddEmbeddedEnhancements(spec, sources.sddEmbeddedSkills ?? new Set());
+    applyDefaultReadOnlyRetryPolicy(spec);
     parseDagSpec(spec);
     assertValidDagSpec(spec);
     return spec;
@@ -778,8 +793,9 @@ function buildFrontendHybridDagFromTask(sources) {
         adapterCommands: sources.verifyCommands?.final,
     });
     const spec = {
-        version: 2,
+        version: 3,
         title: `Frontend implementation DAG: ${taskConfig.title}`,
+        runtimeContract: GENERATED_DAG_RUNTIME_CONTRACT,
         objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
         successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
         globalConstraints,
@@ -1028,6 +1044,361 @@ function buildFrontendHybridDagFromTask(sources) {
             },
         ],
     };
+    applyDefaultReadOnlyRetryPolicy(spec);
+    parseDagSpec(spec);
+    assertValidDagSpec(spec);
+    return spec;
+}
+// ---------------------------------------------------------------------------
+// Backend test DAG template
+// ---------------------------------------------------------------------------
+function buildAnalyzeInputsNode(sources) {
+    return {
+        id: "analyze-inputs-pi",
+        depends_on: [],
+        role: "planner",
+        executor: "pi",
+        complexity: "MED",
+        writePolicy: "read-only",
+        allowedPaths: commonReadOnlyPaths(sources),
+        forbiddenPaths: commonForbiddenPaths(sources),
+        outputContract: "Structured Markdown extracting core content from source documents. No file writes.",
+        subtask_prompt: [
+            "Read the task source materials and extract the following structured content for downstream test generation.",
+            "",
+            "## Required Output Sections:",
+            "",
+            "### 1. API Endpoints",
+            "List all API endpoints: Method, Path, Description, Request params, Response format.",
+            "",
+            "### 2. Data Model",
+            "For each table/collection: fields, types, constraints, descriptions.",
+            "",
+            "### 3. Business Logic",
+            "Core business rules, validation rules, calculation formulas.",
+            "",
+            "### 4. State Transitions",
+            "State machines (e.g. order status: pending → paid → shipped → completed).",
+            "",
+            "### 5. Error Scenarios & Error Codes",
+            "All error codes, error messages, and when they occur.",
+            "",
+            "### 6. External Dependencies",
+            "Third-party services, databases, message queues. Include timeout settings if documented.",
+            "",
+            "### 7. Acceptance Criteria",
+            "Extract ALL acceptance criteria from 需求.md. Number them AC-001, AC-002, etc. If not explicitly listed, derive from functional requirements.",
+            "",
+            "### 8. Risk Areas",
+            "High-risk areas requiring extra test coverage.",
+            "",
+            "## Conditional Sections (include ONLY if mentioned in requirements):",
+            "- Authentication & Authorization: include ONLY if requirements mention auth mechanism (JWT, OAuth2, API Key, etc.)",
+            "- Timeout Handling: include ONLY if requirements mention timeout configuration or degradation strategy",
+            "- Concurrency & Idempotency: include ONLY if requirements mention concurrency, idempotency rules, or locking mechanisms",
+            "- State Transitions: include ONLY if requirements mention business state machines",
+            "- If not mentioned in requirements, do NOT include these sections",
+            "",
+            "This output will be used directly by downstream nodes. Be thorough and structured.",
+            "Read-only: do not modify code, docs, artifacts, or repository files.",
+            buildSourceContextBlock(sources),
+        ].join("\n\n"),
+    };
+}
+function buildGenerateBackendFunctionalCasesNode(sources) {
+    return {
+        id: "generate-backend-functional-cases-pi",
+        depends_on: ["analyze-inputs-pi"],
+        role: "implementer",
+        executor: "pi",
+        toolProfile: "write",
+        complexity: "MED",
+        writePolicy: "exclusive",
+        writeSet: ["testcase/md/**"],
+        allowedPaths: ["testcase/md/**"],
+        forbiddenPaths: commonForbiddenPaths(sources),
+        // 注意：Pi 节点超时由 executor 层控制（默认 30 分钟）
+        // 如需调整，在 harness.json 的 executors.pi 中配置 modelConfig.timeoutMs
+        subtask_prompt: [
+            "Based on the upstream analyze-inputs-pi output, generate structured backend functional test cases.",
+            "",
+            "## Output Steps (do in order):",
+            "1. First, output a brief summary: how many modules, how many cases planned per module",
+            "2. Then write each test case file under testcase/md/",
+            "",
+            "## Format Rules:",
+            "- Each test case ID: BE-<MODULE>-<NNN> (e.g. BE-ORDER-001)",
+            "- Each file covers one module",
+            "- Case structure: ID, Title, Precondition, Steps, Expected Result",
+            "- Map each case to acceptance criteria (AC-xxx)",
+            "",
+            "## Coverage Requirements:",
+            "- Positive paths: happy path for each acceptance criterion",
+            "- Negative paths: error scenarios (invalid input, not found, state violations)",
+            "- Boundary conditions: empty input, max length, edge values",
+            "",
+            "## Conditional Coverage (include ONLY if mentioned in upstream analysis):",
+            "- State transitions: include ONLY if upstream analyze-inputs-pi mentions state machine",
+            "- Authentication scenarios: include ONLY if upstream analyze-inputs-pi mentions auth mechanism",
+            "- Timeout scenarios: include ONLY if upstream analyze-inputs-pi mentions timeout handling",
+            "- Concurrency scenarios: include ONLY if upstream analyze-inputs-pi mentions concurrency/idempotency rules",
+            "- If not mentioned, do NOT generate these test cases",
+            "",
+            "## Constraints:",
+            "- Stay within writeSet: testcase/md/**",
+            "- Do NOT re-read source documents — use the upstream analyze-inputs-pi output only",
+            "- Do not write root artifacts/**",
+        ].join("\n\n"),
+    };
+}
+function buildReviewBackendCasesNode(sources) {
+    return {
+        id: "review-backend-cases-pi",
+        depends_on: ["generate-backend-functional-cases-pi"],
+        role: "reviewer",
+        executor: "pi",
+        complexity: "HIGH",
+        writePolicy: "read-only",
+        allowedPaths: commonReadOnlyPaths(sources),
+        forbiddenPaths: commonForbiddenPaths(sources),
+        outputContract: "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision; followed by Findings and Coverage Assessment. No file writes.",
+        subtask_prompt: [
+            "Review the generated backend functional test cases under testcase/md/.",
+            "",
+            "## Mandatory First Line:",
+            "First non-empty line must be exactly: VERDICT: pass or VERDICT: request-revision",
+            "",
+            "## Review Checklist:",
+            "- ID format: every case uses BE-<MODULE>-<NNN>",
+            "- Positive coverage: each acceptance criterion (AC-xxx) has happy-path case",
+            "- Negative coverage: error scenarios (invalid input, not found, state violations)",
+            "- Boundary coverage: edge cases (empty, max length, edge values)",
+            "- Traceability: each AC maps to at least one case ID",
+            "- Case structure: ID, Title, Precondition, Steps, Expected Result",
+            "- No duplicate IDs across files",
+            "",
+            "## Conditional Coverage (check ONLY if mentioned in upstream analysis):",
+            "- State transition coverage: check ONLY if analyze-inputs-pi mentions state machine",
+            "- Authentication coverage: check ONLY if analyze-inputs-pi mentions auth mechanism",
+            "- Timeout coverage: check ONLY if analyze-inputs-pi mentions timeout handling",
+            "- Concurrency coverage: check ONLY if analyze-inputs-pi mentions concurrency/idempotency rules",
+            "- If not mentioned, do NOT flag as missing",
+            "",
+            "## Verdict Rules:",
+            "- All Critical checks pass + Important findings ≤ 2 → VERDICT: pass",
+            "- Any Critical fails OR Important > 2 → VERDICT: request-revision",
+            "",
+            "## Output After Verdict:",
+            "1. Coverage Assessment table (AC → case IDs)",
+            "2. Findings list (Critical/Important/Informational)",
+            "3. Statistics (total cases, positive/negative/boundary breakdown)",
+            "",
+            "## Constraints:",
+            "- Read-only: do not modify files",
+            "- Do NOT re-read source documents — use upstream analyze-inputs-pi output for acceptance criteria",
+            "- Use testcase/md/ files for case review",
+        ].join("\n\n"),
+    };
+}
+function buildReviewBackendCasesGateNode(sources) {
+    return {
+        id: "review-backend-cases-gate-shell",
+        depends_on: ["review-backend-cases-pi"],
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: commonReadOnlyPaths(sources),
+        forbiddenPaths: commonForbiddenPaths(sources),
+        outputContract: "Deterministic backend case review gate: exit 0 only when review-backend-cases-pi emits VERDICT: pass.",
+        subtask_prompt: "Deterministic gate: block pytest generation unless backend case review emitted VERDICT: pass.",
+        shell: {
+            commands: [],
+            verdictGate: {
+                fromNodeId: "review-backend-cases-pi",
+                accept: ["VERDICT: pass"],
+                label: "backend case review",
+                lineMode: "first-verdict-line",
+            },
+            cwd: ".",
+            timeoutMs: 60000,
+        },
+    };
+}
+function buildGenerateBackendPytestNode(sources) {
+    return {
+        id: "generate-backend-pytest-pi",
+        depends_on: ["review-backend-cases-gate-shell"],
+        role: "implementer",
+        executor: "pi",
+        toolProfile: "write",
+        complexity: "HIGH",
+        writePolicy: "exclusive",
+        writeSet: ["testcase/**/test_*.py"],
+        allowedPaths: ["testcase/**/test_*.py"],
+        forbiddenPaths: commonForbiddenPaths(sources),
+        // 注意：Pi 节点超时由 executor 层控制（默认 30 分钟）
+        // 如需调整，在 harness.json 的 executors.pi 中配置 modelConfig.timeoutMs
+        subtask_prompt: [
+            "Convert the reviewed test cases under testcase/md/ into pytest automation code.",
+            "",
+            "## Output Steps (do in order):",
+            "1. First, output a brief summary: how many files, how many test functions planned",
+            "2. Then write each test file under testcase/",
+            "",
+            "## Format Rules:",
+            "- File prefix: test_<module>.py",
+            "- Function name: test_BE_<MODULE>_<NNN>_<description>",
+            "- Docstring first line: BE-<MODULE>-<NNN>: <Case Title>",
+            "- 1:1 mapping: each functional case → one pytest function",
+            "",
+            "## Implementation Rules:",
+            "- Use assert statements, not unittest assertions",
+            "- Assert specific values, not just 'no exception'",
+            "- Use @pytest.mark.parametrize for boundary cases",
+            "- Use markers: @pytest.mark.positive, @pytest.mark.negative, @pytest.mark.boundary",
+            "",
+            "## Conditional Implementation (include ONLY if test cases exist):",
+            "- Authentication tests: implement ONLY if testcase/md/ contains auth-related cases",
+            "- Timeout tests: implement ONLY if testcase/md/ contains timeout-related cases",
+            "- Use @pytest.mark.auth for auth tests, @pytest.mark.timeout for timeout tests",
+            "- If no such cases exist, do NOT add these tests",
+            "",
+            "## Constraints:",
+            "- Only create NEW files, do NOT modify existing framework files (conftest.py, pytest.ini, pyproject.toml)",
+            "- If filename exists, add suffix: test_order.py → test_order_01.py",
+            "- Stay within writeSet: testcase/**/test_*.py",
+            "- Do NOT re-read source documents — use the reviewed cases under testcase/md/ only",
+            "- Read existing conftest.py/pytest.ini to understand conventions, but do NOT modify them",
+        ].join("\n\n"),
+    };
+}
+function buildExecuteBackendPytestNode(sources) {
+    return {
+        id: "execute-backend-pytest-shell",
+        depends_on: ["generate-backend-pytest-pi"],
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: commonReadOnlyPaths(sources),
+        forbiddenPaths: commonForbiddenPaths(sources),
+        outputContract: "Archived pytest stdout/stderr with exit codes and HTML report path; no source or test file modifications.",
+        subtask_prompt: "Run pytest for the backend test suite and capture results.",
+        shell: {
+            commands: [
+                "python -m pytest testcase/ --html=reports/backend-test-report.html -v",
+            ],
+            verifyEvidence: buildVerifyEvidence({
+                phase: "final",
+                quota: "full",
+                commandSource: "inline",
+                fallbackCommands: [
+                    "python -m pytest testcase/ --html=reports/backend-test-report.html -v",
+                ],
+                finalFullRequired: true,
+            }),
+            cwd: ".",
+            timeoutMs: 300000,
+        },
+    };
+}
+function buildTestRetrospectNode(sources) {
+    return {
+        id: "test-retrospect-pi",
+        depends_on: ["execute-backend-pytest-shell"],
+        role: "closeout",
+        executor: "pi",
+        toolProfile: "write",
+        complexity: "MED",
+        writePolicy: "exclusive",
+        writeSet: ["docs/test-reports/**"],
+        allowedPaths: ["docs/test-reports/**"],
+        forbiddenPaths: commonForbiddenPaths(sources),
+        subtask_prompt: [
+            "Read upstream outputs (review report + pytest results) and generate a test retrospective report.",
+            "",
+            "## Output Steps (do in order):",
+            "1. First, output the maturity rating on the first line: Rating: A/B/C/D",
+            "2. Then write the full report under docs/test-reports/",
+            "",
+            "## Report Structure:",
+            "1. Maturity Rating with rationale",
+            "2. Test Coverage Summary (total cases, pass rate, failed case analysis)",
+            "3. Review Findings and resolution status",
+            "4. Failed Test Analysis (if any)",
+            "5. Recommendations for improvement",
+            "",
+            "## Rating Criteria:",
+            "- A: 100% acceptance criteria covered + 100% pytest pass + no Critical findings",
+            "- B: ≥80% coverage + ≥90% pass + Low findings only",
+            "- C: ≥60% coverage + ≥70% pass + no Critical findings",
+            "- D: below C thresholds",
+            "",
+            "## Constraints:",
+            "- Stay within writeSet: docs/test-reports/**",
+            "- Do NOT re-read source documents — use upstream outputs only",
+            "- Do not write root artifacts/**",
+        ].join("\n\n"),
+    };
+}
+const BACKEND_TEST_DEFAULTS = {
+    ...HYBRID_DEFAULTS,
+    writePolicy: "read-only",
+};
+const BACKEND_TEST_SKILLS_BY_ROLE = {
+    planner: ["loop-agent"],
+    scout: [],
+    implementer: ["test-driven-development", "verification-before-completion"],
+    reviewer: ["requesting-code-review", "code-review-core"],
+    verifier: ["verification-before-completion", "systematic-debugging"],
+    closeout: ["loop-agent", "verification-before-completion"],
+};
+function buildBackendTestHybridDag(sources) {
+    const { taskConfig } = sources;
+    const sourceContext = buildSourceContextBlock(sources);
+    const readOnlyPaths = commonReadOnlyPaths(sources);
+    const forbiddenPaths = commonForbiddenPaths(sources);
+    const globalConstraints = [
+        ...taskConfig.hardConstraints,
+        ...(sources.constraintMarkdown
+            ? [`See 执行约束.md in task source (${sources.taskId})`]
+            : []),
+        ...STANDARD_GLOBAL_CONSTRAINTS,
+        "backend-test-dag nodes must maintain traceability from requirements to functional cases to pytest automation.",
+        "Functional test case IDs must use BE-<MODULE>-<NNN> format.",
+        "pytest execution must produce HTML reports under reports/.",
+        "pytest automation scripts must use test_ filename prefix for pytest discovery.",
+        "generate-backend-pytest-pi must only create new test files under testcase/; modifying existing framework files (conftest.py, pytest.ini, pyproject.toml) is forbidden.",
+        "review-backend-cases-gate-shell must block pytest generation unless the review verdict is exactly VERDICT: pass.",
+        "If a target test filename already exists under testcase/, add a numeric suffix (_01, _02, ...); never overwrite or append to existing files.",
+        "execute-backend-pytest-shell must not modify test assertions or production code to make tests pass; test failures indicate potential implementation issues and must be reported honestly.",
+    ];
+    const spec = {
+        version: 3,
+        title: `Backend test DAG: ${taskConfig.title}`,
+        runtimeContract: GENERATED_DAG_RUNTIME_CONTRACT,
+        outputLanguage: sources.outputLanguage ?? DEFAULT_DAG_OUTPUT_LANGUAGE,
+        objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
+        successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
+        globalConstraints,
+        defaults: {
+            ...BACKEND_TEST_DEFAULTS,
+            contextProfile: taskConfig.contextProfile,
+        },
+        skillsByRole: BACKEND_TEST_SKILLS_BY_ROLE,
+        executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
+        tasks: [
+            buildAnalyzeInputsNode(sources),
+            buildGenerateBackendFunctionalCasesNode(sources),
+            buildReviewBackendCasesNode(sources),
+            buildReviewBackendCasesGateNode(sources),
+            buildGenerateBackendPytestNode(sources),
+            buildExecuteBackendPytestNode(sources),
+            buildTestRetrospectNode(sources),
+        ],
+    };
+    applyDefaultReadOnlyRetryPolicy(spec);
     parseDagSpec(spec);
     assertValidDagSpec(spec);
     return spec;
@@ -1037,6 +1408,10 @@ export function buildHybridDagFromTask(sources, options = {}) {
         options.template === "frontend-implementation") {
         return buildFrontendHybridDagFromTask(sources);
     }
+    if (sources.taskConfig.taskKind === "backend-test" ||
+        options.template === "backend-test-dag") {
+        return buildBackendTestHybridDag(sources);
+    }
     const standard = buildStandardHybridDagFromTask(sources);
     const template = options.template ?? "standard-dag";
     if (template === "standard-dag")
@@ -1048,6 +1423,21 @@ export function buildHybridDagFromTask(sources, options = {}) {
 function cloneTask(task, patch = {}) {
     return { ...task, ...patch };
 }
+/**
+ * Apply the default read-only Pi retry policy to safe planner/scout/reviewer/
+ * verifier/closeout Pi nodes in the generated DAG. Writers, supervisors,
+ * dynamic, shell, static, and decision-gate nodes are skipped. Idempotent:
+ * never overwrites an explicit retryPolicy a task already declares.
+ */
+function applyDefaultReadOnlyRetryPolicy(spec) {
+    for (const task of spec.tasks) {
+        if (task.retryPolicy !== undefined)
+            continue;
+        if (isSafeReadOnlyPiRetryCandidate(task)) {
+            task.retryPolicy = DEFAULT_READ_ONLY_PI_RETRY_POLICY;
+        }
+    }
+}
 function getTaskOrThrow(spec, id) {
     const task = spec.tasks.find((item) => item.id === id);
     if (!task)
@@ -1135,6 +1525,7 @@ function buildReviewGatedHybridDag(standard, sources) {
     replaceTask(spec, cloneTask(closeout, { depends_on: ["review-gate-shell"] }));
     spec.tasks.splice(spec.tasks.length - 1, 0, buildReviewNode(sources), buildReviewGateNode(sources));
     applySddEmbeddedEnhancements(spec, sources.sddEmbeddedSkills ?? new Set());
+    applyDefaultReadOnlyRetryPolicy(spec);
     parseDagSpec(spec);
     assertValidDagSpec(spec);
     return spec;
@@ -1263,6 +1654,7 @@ function buildProcessGateNode(sources) {
             },
             repairArtifactGate: {
                 fromNodeId: "process-supervisor-pi",
+                repairNodeId: repairNodeId(),
             },
             cwd: ".",
             timeoutMs: 60000,
@@ -1405,6 +1797,7 @@ function buildSupervisedHybridDag(standard, sources) {
         ],
     };
     applySddEmbeddedEnhancements(spec, sources.sddEmbeddedSkills ?? new Set());
+    applyDefaultReadOnlyRetryPolicy(spec);
     parseDagSpec(spec);
     assertValidDagSpec(spec);
     return spec;

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

@@ -3,10 +3,12 @@ import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHuman
 import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
 import { buildDagNodePromptEnvelope } from "./prompt.js";
 import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
+import { computeBackoffDelayMs, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, } from "./retry-policy.js";
+import { writeDagNodeJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { assertSkillSnapshotCoversSpec, buildNodePromptFromSnapshot, isDagSkillSnapshotIntegrityError, readSkillSnapshot, } from "./skill-snapshot.js";
 import { resolveDagSkillInstructions, skillInstructionMetadata, } from "./skill-instructions.js";
 import { resolveDagNodeSkills } from "./skills.js";
-import { parseRepairArtifactFromText, validateRepairArtifactScope, } from "./repair-artifact.js";
+import { parseRepairArtifactFromText, resolveRepairTaskForGate, validateRepairArtifactScope, } from "./repair-artifact.js";
 import { resolveModelForTask, } from "./types.js";
 export function buildNodePrompt(spec, task, upstream) {
     return buildDagNodePromptEnvelope({
@@ -54,10 +56,6 @@ function assertRepairArtifactVerdictMatchesSupervisor(input) {
         throw new Error(`repair artifact gate failed: verdict mismatch between supervisor ${supervisorVerdict} and REPAIR_ARTIFACT_JSON ${input.artifactVerdict}`);
     }
 }
-function findRepairTaskForGate(input) {
-    return Array.from(input.tasksById.values()).find((candidate) => candidate.depends_on.includes(input.gateTask.id) &&
-        candidate.id === "repair-pi");
-}
 function parseSupervisorRepairArtifact(node) {
     const text = `${node?.assistantText ?? ""}\n${node?.stdout ?? ""}`;
     return parseRepairArtifactFromText(text);
@@ -76,12 +74,21 @@ function validateRepairArtifactGateBeforeShell(input) {
         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: findRepairTaskForGate({
-            tasksById: input.tasksById,
-            gateTask: input.task,
-        }),
+        repairTask: resolution.repairTask,
     });
     if (!scoped.ok) {
         throw new Error(`repair artifact gate failed: ${scoped.reason}`);
@@ -96,6 +103,15 @@ function recordRepairArtifactForSupervisorNode(input) {
         input.node.repairArtifact = parsed.artifact;
     }
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+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") {
@@ -223,31 +239,109 @@ export async function executeDagNode(input) {
     node.resolvedSkills = resolvedSkills;
     await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
     const model = resolveModelForTask(task, spec.executorModels);
-    const started = Date.now();
-    try {
-        validateRepairArtifactGateBeforeShell({
-            task,
-            tasksById,
-            state,
-        });
-        const result = await executeNode({ task, cwd, model, prompt });
-        node.durationMs = result.durationMs ?? Date.now() - started;
+    const retryPolicy = task.retryPolicy && isSafeReadOnlyPiRetryCandidate(task)
+        ? task.retryPolicy
+        : undefined;
+    const maxAttempts = retryPolicy?.maxAttempts ?? 1;
+    const attempts = [];
+    let totalBackoffMs = 0;
+    let terminalResult;
+    for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
+        const attemptStartedAt = new Date().toISOString();
+        const attemptStarted = Date.now();
+        let result;
+        try {
+            validateRepairArtifactGateBeforeShell({
+                task,
+                tasksById,
+                state,
+            });
+            result = await executeNode({ task, cwd, model, prompt });
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - attemptStarted,
+            };
+        }
+        const attemptFinishedAt = new Date().toISOString();
+        const attemptRecord = {
+            attempt: attemptNumber,
+            startedAt: attemptStartedAt,
+            finishedAt: attemptFinishedAt,
+            durationMs: result.durationMs ?? Date.now() - attemptStarted,
+            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 =
+            retryPolicy === undefined
+                ? attemptRecord.durationMs
+                : attempts.reduce((sum, attempt) => sum + (attempt.durationMs ?? 0), 0) +
+                    totalBackoffMs;
         node.stdout = result.stdout;
         node.stderr = result.stderr;
         node.failureCategory = result.failureCategory;
-        if (result.assistantText !== undefined) {
-            node.assistantText = result.assistantText;
-        }
-        if (result.backend !== undefined)
-            node.backend = result.backend;
-        if (result.sdkAttempted !== undefined) {
-            node.sdkAttempted = result.sdkAttempted;
+        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 (retryPolicy !== undefined) {
+            state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+            await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+            await input.persistState();
         }
-        if (result.tokensUsed !== undefined)
-            node.tokensUsed = result.tokensUsed;
-        if (result.parsedEvents !== undefined) {
-            node.parsedEvents = result.parsedEvents;
+        terminalResult = result;
+        if (result.ok)
+            break;
+        const canRetry = retryPolicy !== undefined && attemptNumber < maxAttempts;
+        const retryable = retryPolicy !== undefined &&
+            isRetryablePiFailureCategory(result.failureCategory, {
+                retryCategories: retryPolicy.retryCategories,
+            });
+        if (!canRetry || !retryable)
+            break;
+        const delayMs = computeBackoffDelayMs(attemptNumber + 1, retryPolicy);
+        if (delayMs > 0) {
+            totalBackoffMs += delayMs;
+            await sleep(delayMs);
+            // 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();
         }
+    }
+    const result = terminalResult;
+    const started = Date.now();
+    try {
         recordRepairArtifactForSupervisorNode({
             task,
             node,