@tea-agent/loop-agent 0.39.0-next.3 → 0.39.0-next.30

package/dist/executors/shell-executor.js

@@ -15,6 +15,8 @@ import { materializeBackendTestAnalysisContract } from "../workflows/dag/backend
 import { extractBackendTestContractEnvelope } from "../workflows/dag/backend-test-contract-envelope.js";
 import { materializeFrontendImplementationContract } from "../workflows/dag/frontend-implementation-contract.js";
 import { materializeFrontendTestResult, validateFrontendCaseEvidence, } from "../workflows/dag/frontend-test-result-contract.js";
+import { copyFrontendTestStandardScenarios } from "../workflows/dag/frontend-test-standard-scenarios.js";
+import { probeFrontendTestEnvironment } from "../workflows/dag/frontend-test-environment-probe.js";
 import { renderFrontendTestL5Report } from "../workflows/dag/frontend-test-l5-report.js";
 import { validateFrontendCaseChecklist } from "../workflows/dag/frontend-test-case-checklist.js";
 import { materializeFrontendTestCaseManifest } from "../workflows/dag/frontend-test-case-manifest.js";
@@ -27,11 +29,13 @@ import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from
 import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } from "../workflows/dag/frontend-lint-baseline.js";
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
+import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
+import { backendTestGapDocSchema, ingestBackendTestGap, } from "../workflows/dag/backend-test-gap-fill.js";
 import { analyzeBackendTestCaseCoverage, analyzeBackendTestMarkdownPytestCorrespondence, materializeBackendTestCaseManifestFromFacts, } from "../workflows/dag/backend-test-case-coverage-analysis.js";
 import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport, } from "../workflows/dag/backend-test-result-contract.js";
-import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, resolveBackendTestMappedPytestScripts, collectJacocoCoverage, hasBlockingBackendMarkdownSafetyFindings, hasBlockingBackendMarkdownModuleStemFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, resolveBackendTestMappedPytestScripts, collectJacocoCoverage, hasBlockingBackendMarkdownSafetyFindings, hasBlockingBackendMarkdownModuleStemFindings, inspectBackendTestEnvironment, markdownFiles, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
 import { applyDeterministicScenarioParamRepairs, assessBackendScenarioParamConsistency, classifyBackendTestFailureWithScenarioParam, readBackendScenarioParamFacts, renderBackendTestFailureAnalysis, writeBackendScenarioParamArtifacts, writeScenarioParamRepairAudit, } from "../workflows/dag/backend-test-scenario-param.js";
-import { assessBackendPytestCollection, assessMissingBackendPytestScripts, assessPriorityOnlyBackendPytestModules, assertBackendTestExecutionReadinessFresh, buildBackendPytestAssetInventory, materializeBackendTestExecutionReadiness, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, readBackendTestExecutionReadiness, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.js";
+import { assessBackendPytestCollection, assessMissingBackendPytestScripts, assessPriorityOnlyBackendPytestModules, assertBackendTestExecutionReadinessFresh, buildBackendPytestAssetInventory, buildBackendTestItemEligibility, materializeBackendTestExecutionReadiness, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, readBackendTestExecutionReadiness, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.js";
 import { computeL5ReportMetrics } from "../workflows/dag/l5-report-metrics.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
@@ -48,6 +52,7 @@ async function runBackendScenarioParamPreflight(input) {
         phase: "initial",
         repairAttempt: 0,
         strictScenarioParamGate: input.strictScenarioParamGate,
+        layout: input.layout,
     });
     const initialArtifacts = await writeBackendScenarioParamArtifacts({
         runDir: input.runDir,
@@ -73,6 +78,7 @@ async function runBackendScenarioParamPreflight(input) {
             phase: "final",
             repairAttempt: 1,
             strictScenarioParamGate: input.strictScenarioParamGate,
+            layout: input.layout,
         });
         finalFacts = reassessed.facts;
         finalMarkdown = reassessed.markdown;
@@ -117,6 +123,39 @@ function shouldReuseSuccessfulShellCommands(shell) {
 const DEFAULT_SHELL_TIMEOUT_MS = 300_000;
 const SUMMARY_STDOUT_MAX = 4_000;
 const SUMMARY_STDERR_MAX = 2_000;
+const TEST_TIMEOUT_CLASSIFY_MAX_CHARS = 8_000;
+const TEST_TIMEOUT_MARKERS = [
+    /Test timed out in \d+ms/i,
+    /Timeout of \d+ms exceeded/i,
+];
+const DETERMINISTIC_NON_TIMEOUT_FAILURE_MARKERS = [
+    /AssertionError/i,
+    /expected:?\s/i,
+    /received:?\s/i,
+    /Snapshot /i,
+    /toMatchSnapshot/i,
+    /SyntaxError/i,
+    /TS\d{4}/,
+    /error TS/i,
+    /eslint/i,
+    /compile error/i,
+    /Failed to compile/i,
+];
+function isIdentifiedTestCommand(command) {
+    return /(?:^|[\s"'`])(?:npx\s+)?vitest(?:\s|$)|(?:^|[\s"'`])npm(?:\.cmd)?\s+test(?:\s|$)|(?:^|[\s"'`])pnpm(?:\.cmd)?\s+test(?:\s|$)|(?:^|[\s"'`])yarn(?:\.cmd)?\s+test(?:\s|$)/i.test(command);
+}
+function classifyShellCommandFailure(input) {
+    if (input.processCategory !== "nonzero-exit")
+        return input.processCategory;
+    if (!isIdentifiedTestCommand(input.command))
+        return "nonzero-exit";
+    const sample = `${input.stdout}\n${input.stderr}`.slice(0, TEST_TIMEOUT_CLASSIFY_MAX_CHARS);
+    const hasTimeoutMarker = TEST_TIMEOUT_MARKERS.some((marker) => marker.test(sample));
+    if (!hasTimeoutMarker)
+        return "nonzero-exit";
+    const mixedDeterministicFailure = DETERMINISTIC_NON_TIMEOUT_FAILURE_MARKERS.some((marker) => marker.test(sample));
+    return mixedDeterministicFailure ? "nonzero-exit" : "test-timeout";
+}
 const NODE_STDOUT_MAX = 12_000;
 const NODE_STDERR_MAX = 8_000;
 const MAX_BUFFERED_OUTPUT_BYTES = 64 * 1024;
@@ -323,16 +362,21 @@ export async function executeShellCommand(input) {
             });
         });
         child.on("close", (code) => {
-            let failureCategory = "nonzero-exit";
+            let processCategory = "nonzero-exit";
             if (timedOut) {
-                failureCategory = "timeout";
+                processCategory = "timeout";
             }
             else if (code === 0) {
-                failureCategory = "success";
+                processCategory = "success";
             }
             finish({
                 exitCode: code,
-                failureCategory,
+                failureCategory: classifyShellCommandFailure({
+                    command: input.command,
+                    processCategory,
+                    stdout: formatBoundedOutput(stdout),
+                    stderr: formatBoundedOutput(stderr),
+                }),
                 ok: code === 0 && !timedOut,
             });
         });
@@ -492,11 +536,114 @@ async function readAdvisoryRunReport(reportsDir, filename, title) {
 async function executeBackendTestPipeline(input, meta) {
     const pipeline = input.task.shell?.backendTestPipeline;
     const started = Date.now();
+    // Plan A: prefer the frozen layout carried by the compiled spec; fall back
+    // to the historical default for hand-written legacy DAGs.
+    const backendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
+        ? {
+            testRoot: meta.spec.backendTestLayout.testRoot,
+            markdownRel: meta.spec.backendTestLayout.markdownRel,
+            scriptRel: meta.spec.backendTestLayout.scriptRel,
+        }
+        : undefined);
     try {
         if (!pipeline)
             throw new Error("missing backend-test pipeline id");
         const outputs = [];
-        if (pipeline === "markdown-environment") {
+        if (pipeline === "ingest-backend-test-gap") {
+            // Plan D: deterministic gap ingest. Identity (taskId + requirement
+            // sha256) is fail-closed; a mismatched plan blocks every writer.
+            const gapDocRel = meta.spec.globalConstraints
+                ?.map((item) => /^backendTestGapDoc=(.+)$/i.exec(item.trim())?.[1])
+                .find(Boolean);
+            const binding = meta.spec.sourceBinding;
+            const requirementSha256 = binding?.sources.find((s) => s.kind === "requirement")?.sha256 ?? "";
+            if (!gapDocRel || !binding || !requirementSha256) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: "backend-test gap ingest requires the bound gap document path and the task source binding with a requirement sha256",
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            const gapDocAbs = path.join(input.cwd, ...gapDocRel.split("/"));
+            let parsed;
+            try {
+                parsed = JSON.parse(await readFile(gapDocAbs, "utf8"));
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: `backend-test gap document is unreadable JSON at ${gapDocRel}: ${error instanceof Error ? error.message : String(error)}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            const doc = backendTestGapDocSchema.safeParse(parsed);
+            if (!doc.success) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: `invalid backend-test-gap-v1 document: ${doc.error.issues
+                        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+                        .join("; ")}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            // previous N6 facts (may be absent on a fresh checkout)
+            const factsPath = path.join(input.cwd, "contracts", "backend-test-case-coverage-facts.json");
+            let previousMissingSlots;
+            let previousCoveredSlots;
+            try {
+                const facts = JSON.parse(await readFile(factsPath, "utf8"));
+                previousMissingSlots = facts.scenarioPartitions?.missingSlots;
+                previousCoveredSlots = (facts.rules ?? []).flatMap((rule) => rule.coveredTestPoints ?? []);
+            }
+            catch {
+                // no previous facts in the workspace: the gap doc alone drives the plan
+            }
+            // module index comes from the README on disk
+            let existingModuleStems = [];
+            try {
+                const files = await markdownFiles(input.cwd, backendLayout);
+                existingModuleStems = files
+                    .map((file) => path.basename(file, ".md"))
+                    .filter((stem) => stem.toLowerCase() !== "readme");
+            }
+            catch {
+                // no markdown tree: every slot becomes a conflict
+            }
+            const plan = ingestBackendTestGap({
+                gapDoc: doc.data,
+                previousMissingSlots,
+                previousCoveredSlots,
+                existingModuleStems,
+                sharedSetupPath: meta.spec.backendTestSharedSetup?.path ?? null,
+                layout: backendLayout,
+                taskId: binding.taskId,
+                requirementSha256,
+            });
+            const contractsDir = path.join(meta.runDir, "contracts");
+            await mkdir(contractsDir, { recursive: true });
+            const planPath = path.join(contractsDir, "backend-test-gap-plan-v1.json");
+            await writeFile(planPath, JSON.stringify(plan, null, 2), "utf8");
+            outputs.push(`gapPlan=${planPath}`, `gapPlanStatus=${plan.status}`);
+            if (plan.status === "error") {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: [
+                        "backend-test gap ingest failed closed (identity/conflicts):",
+                        ...plan.conflicts,
+                    ].join("\n"),
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
+        else if (pipeline === "markdown-environment") {
             const results = await executePipelineCommands(input, meta);
             if (!results.every((result) => result.ok)) {
                 const failure = results.find((result) => !result.ok);
@@ -530,6 +677,8 @@ async function executeBackendTestPipeline(input, meta) {
                     environmentMarkdown,
                     requiredRequirementIds,
                     sourceBinding: meta.spec.sourceBinding,
+                    layout: backendLayout,
+                    sharedSetup: meta.spec.backendTestSharedSetup ?? null,
                 });
             }
             catch (error) {
@@ -583,6 +732,7 @@ async function executeBackendTestPipeline(input, meta) {
                 const coverage = await analyzeBackendTestCaseCoverage({
                     workspaceRoot: input.cwd,
                     sourceBinding: normalizedBinding,
+                    layout: backendLayout,
                 });
                 const coveragePath = await writeRunReport(meta.runDir, "backend-test-case-coverage-analysis.md", coverage.markdown);
                 const contractsDir = path.join(meta.runDir, "contracts");
@@ -590,6 +740,23 @@ async function executeBackendTestPipeline(input, meta) {
                 const factsPath = path.join(contractsDir, "backend-test-case-coverage-facts.json");
                 await writeFile(factsPath, JSON.stringify(coverage.facts, null, 2), "utf8");
                 outputs.push(`caseCoverage=${coveragePath}`, `caseCoverageFacts=${factsPath}`, coverage.markdown);
+                // Plan C: scenario-partition slot coverage is fail-closed. General
+                // coverage findings stay advisory, but a declared filter axis missing
+                // an each-value/omitted slot or its complement slot must block pytest
+                // generation until the Markdown declares the slot.
+                const partitionBlocking = coverage.facts.findings.filter((finding) => /^(?:MISSING_PARTITION|MISSING_PARTITION_SLOT|MISSING_COMPLEMENT_SLOT|MISSING_PARTITION_TABLE|INVALID_PARTITION_DOMAIN|NO_FINITE_DOMAIN|PARTITION_SOURCE_MISMATCH)/.test(finding));
+                if (partitionBlocking.length > 0) {
+                    return {
+                        ok: false,
+                        stdout: outputs.join("\n\n"),
+                        stderr: [
+                            "backend-test scenario partitions are incomplete (fail-closed):",
+                            ...partitionBlocking,
+                        ].join("\n"),
+                        failureCategory: "invalid-output",
+                        durationMs: Date.now() - started,
+                    };
+                }
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -606,9 +773,9 @@ async function executeBackendTestPipeline(input, meta) {
             }
         }
         else if (pipeline === "markdown-collection-assess") {
-            const resolution = await resolveBackendTestMappedPytestScripts(input.cwd);
+            const resolution = await resolveBackendTestMappedPytestScripts(input.cwd, backendLayout);
             let facts;
-            const preflightInventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false });
+            const preflightInventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false, layout: backendLayout });
             const priorityOnlyFacts = assessPriorityOnlyBackendPytestModules({
                 phase: "initial",
                 mappedScripts: resolution.expectedScripts,
@@ -618,7 +785,7 @@ async function executeBackendTestPipeline(input, meta) {
                 facts = priorityOnlyFacts;
             }
             else if (resolution.missingScripts.length > 0) {
-                const inventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false });
+                const inventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false, layout: backendLayout });
                 facts = assessMissingBackendPytestScripts({
                     mappedScripts: resolution.expectedScripts,
                     existingMappedScripts: resolution.existingScripts,
@@ -632,10 +799,11 @@ async function executeBackendTestPipeline(input, meta) {
                 const scenario = await runBackendScenarioParamPreflight({
                     workspaceRoot: input.cwd,
                     runDir: meta.runDir,
+                    layout: backendLayout,
                     strictScenarioParamGate: Boolean((meta.spec.globalConstraints ?? []).some((item) => /strictScenarioParamGate\s*=\s*true/i.test(item))),
                 });
                 outputs.push(...scenario.outputs);
-                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts);
+                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts, { layout: backendLayout });
                 const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
                 const targets = mappedScripts.map(shellQuote).join(" ");
                 const command = `PYTHONDONTWRITEBYTECODE=1 python -m pytest --collect-only -q -p no:cacheprovider ${targets}`;
@@ -669,6 +837,7 @@ async function executeBackendTestPipeline(input, meta) {
                     fixtureResolution = { exitCode: fixtureResult.exitCode ?? 2, stdout: fixtureResult.stdout, stderr: fixtureResult.stderr };
                 }
                 facts = assessBackendPytestCollection({
+                    layout: backendLayout,
                     phase: "initial",
                     mappedScripts,
                     inventory,
@@ -678,6 +847,43 @@ async function executeBackendTestPipeline(input, meta) {
                     fixtureResolution,
                 });
             }
+            try {
+                const correspondence = await analyzeBackendTestMarkdownPytestCorrespondence({
+                    workspaceRoot: input.cwd,
+                    layout: backendLayout,
+                    taskId: meta.spec.sourceBinding?.taskId ?? "unbound",
+                });
+                const correspondenceReportPath = await writeRunReport(meta.runDir, "backend-test-markdown-pytest-correspondence-initial.md", correspondence.markdown);
+                const contractsDir = path.join(meta.runDir, "contracts");
+                await mkdir(contractsDir, { recursive: true });
+                const correspondenceFactsPath = path.join(contractsDir, "backend-test-markdown-pytest-correspondence-initial.json");
+                await writeFile(correspondenceFactsPath, JSON.stringify(correspondence.facts, null, 2), "utf8");
+                outputs.push(`initialCorrespondence=${correspondenceReportPath}`, `initialCorrespondenceFacts=${correspondenceFactsPath}`);
+                if (correspondence.facts.status === "FAIL" && facts.status === "PASS") {
+                    const correspondenceRepairPaths = Array.from(new Set(correspondence.facts.entries
+                        .filter((entry) => entry.status !== "EXACT_1_TO_1")
+                        .flatMap((entry) => [entry.expectedScript, ...entry.actualScripts])
+                        .filter((candidate) => candidate.startsWith("testcase/") && candidate.endsWith(".py")))).sort();
+                    if (correspondenceRepairPaths.length > 0) {
+                        facts.status = "REPAIRABLE";
+                        facts.repairEligible = true;
+                        facts.repairPaths = Array.from(new Set([...facts.repairPaths, ...correspondenceRepairPaths])).sort();
+                        facts.findings.push({
+                            kind: "markdown-pytest-correspondence",
+                            classification: "test-asset-defect",
+                            repairability: "repairable",
+                            detail: correspondence.facts.entries
+                                .filter((entry) => entry.status !== "EXACT_1_TO_1")
+                                .flatMap((entry) => entry.findings)
+                                .join("; ")
+                                .slice(0, 12_000) || "Markdown-to-pytest correspondence is incomplete",
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                outputs.push(`initialCorrespondence=UNAVAILABLE: ${error instanceof Error ? error.message : String(error)}`);
+            }
             const artifacts = await writeBackendPytestCollectionArtifacts({
                 runDir: meta.runDir,
                 stem: "initial",
@@ -711,14 +917,15 @@ async function executeBackendTestPipeline(input, meta) {
                 });
             }
             else if (initial.status === "REPAIRABLE") {
-                const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
+                const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd, backendLayout);
                 const scenario = await runBackendScenarioParamPreflight({
                     workspaceRoot: input.cwd,
                     runDir: meta.runDir,
+                    layout: backendLayout,
                     strictScenarioParamGate: Boolean((meta.spec.globalConstraints ?? []).some((item) => /strictScenarioParamGate\s*=\s*true/i.test(item))),
                 });
                 outputs.push(...scenario.outputs);
-                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts);
+                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts, { layout: backendLayout });
                 const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
                 const targets = mappedScripts.map(shellQuote).join(" ");
                 const command = `PYTHONDONTWRITEBYTECODE=1 python -m pytest --collect-only -q -p no:cacheprovider ${targets}`;
@@ -753,6 +960,7 @@ async function executeBackendTestPipeline(input, meta) {
                     fixtureResolution = { exitCode: fixtureResult.exitCode ?? 2, stdout: fixtureResult.stdout, stderr: fixtureResult.stderr };
                 }
                 const finalFacts = assessBackendPytestCollection({
+                    layout: backendLayout,
                     phase: "final",
                     mappedScripts,
                     inventory,
@@ -776,12 +984,57 @@ async function executeBackendTestPipeline(input, meta) {
                 facts: effective,
             });
             const scenarioFacts = await readBackendScenarioParamFacts(path.join(meta.runDir, "contracts", "backend-test-scenario-param-consistency-facts.json"));
+            const correspondence = meta.spec.sourceBinding
+                ? await analyzeBackendTestMarkdownPytestCorrespondence({
+                    workspaceRoot: input.cwd,
+                    layout: backendLayout,
+                    taskId: meta.spec.sourceBinding.taskId,
+                })
+                : undefined;
+            const eligibility = correspondence
+                ? buildBackendTestItemEligibility(effective.collectedItemIds, {
+                    correspondenceEntries: correspondence.facts.entries,
+                    scenarioEntries: scenarioFacts.entries,
+                })
+                : { eligibleItemIds: effective.collectedItemIds, excludedItems: [] };
+            const eligibilityInputHashes = Object.fromEntries((correspondence?.facts.inputFiles ?? []).map((item) => [item.path, item.sha256]));
+            const eligibilityFactsPath = path.join(meta.runDir, "contracts", "backend-test-execution-eligibility.json");
+            await mkdir(path.dirname(eligibilityFactsPath), { recursive: true });
+            await writeFile(eligibilityFactsPath, `${JSON.stringify({
+                schemaId: "backend-test-execution-eligibility-v1",
+                status: eligibility.eligibleItemIds.length === 0 ? "BLOCKED" : eligibility.excludedItems.length > 0 ? "PARTIAL" : "PASS",
+                collectedItemCount: effective.collectedItemIds.length,
+                eligibleItemCount: eligibility.eligibleItemIds.length,
+                excludedItemCount: eligibility.excludedItems.length,
+                eligibleItemIds: eligibility.eligibleItemIds,
+                excludedItems: eligibility.excludedItems,
+                inputHashes: eligibilityInputHashes,
+            }, null, 2)}\n`, "utf8");
+            const eligibilityReportPath = await writeRunReport(meta.runDir, "backend-test-execution-eligibility.md", [
+                "# Backend Test Execution Eligibility",
+                "",
+                "## Status",
+                "",
+                eligibility.eligibleItemIds.length === 0 ? "BLOCKED" : eligibility.excludedItems.length > 0 ? "PARTIAL" : "PASS",
+                "",
+                `- Collected items: ${effective.collectedItemIds.length}`,
+                `- Eligible items: ${eligibility.eligibleItemIds.length}`,
+                `- Excluded items: ${eligibility.excludedItems.length}`,
+                "",
+                "## Excluded Items",
+                "",
+                ...(eligibility.excludedItems.length > 0 ? eligibility.excludedItems.map((item) => `- \`${item.itemId}\` (${item.caseId ?? "unknown Case"}): ${item.reasons.join("; ")}`) : ["- None"]),
+                "",
+            ].join("\n"));
+            outputs.push(`executionEligibility=${eligibilityReportPath}`, `executionEligibilityFacts=${eligibilityFactsPath}`);
             const readiness = await materializeBackendTestExecutionReadiness({
                 runDir: meta.runDir,
                 workspaceRoot: input.cwd,
                 effective,
                 scenarioParamStatus: scenarioFacts.overallStatus,
                 scenarioParamRepairAttempt: scenarioFacts.repairAttempt,
+                eligibility,
+                eligibilityInputHashes,
             });
             return {
                 ok: true,
@@ -792,6 +1045,8 @@ async function executeBackendTestPipeline(input, meta) {
                     collectedItemCount: effective.collectedItemCount,
                     fixtureResolutionStatus: effective.fixtureResolutionStatus,
                     executionReadinessStatus: readiness.status,
+                    eligibleItemCount: readiness.eligibleItemIds.length,
+                    excludedItemCount: readiness.excludedItems.length,
                     factsPath: "contracts/backend-test-pytest-collection-effective.json",
                     readinessPath: "contracts/backend-test-execution-readiness.json",
                     reportPath: artifacts.reportPath,
@@ -826,6 +1081,7 @@ async function executeBackendTestPipeline(input, meta) {
             try {
                 const correspondence = await analyzeBackendTestMarkdownPytestCorrespondence({
                     workspaceRoot: input.cwd,
+                    layout: backendLayout,
                     taskId: sourceBinding.taskId,
                 });
                 const correspondencePath = await writeRunReport(meta.runDir, "backend-test-markdown-pytest-correspondence.md", correspondence.markdown);
@@ -888,9 +1144,32 @@ async function executeBackendTestPipeline(input, meta) {
         else if (pipeline === "markdown-execute-html") {
             const executionReadiness = await readBackendTestExecutionReadiness(path.join(meta.runDir, "contracts", "backend-test-execution-readiness.json"));
             await assertBackendTestExecutionReadinessFresh(input.cwd, executionReadiness);
-            const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
-            const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
-            const pytestTargets = mappedScripts.map(shellQuote).join(" ");
+            const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd, backendLayout);
+            let eligibleItemIds = executionReadiness.eligibleItemIds;
+            // Plan D gap-fill executeScope=affected: when a gap plan exists in
+            // this run, prefer the newly planned items (pytest node ids contain
+            // the TP slot id) plus every collected item of the patched modules;
+            // scope=all keeps the full eligible set.
+            const affectedScope = meta.spec.globalConstraints?.some((item) => /^backendTestExecuteScope=affected$/i.test(item.trim())) ?? false;
+            if (affectedScope) {
+                try {
+                    const plan = JSON.parse(await readFile(path.join(meta.runDir, "contracts", "backend-test-gap-plan-v1.json"), "utf8"));
+                    const newPoints = new Set(plan.newTestPoints ?? []);
+                    const modules = new Set((plan.targetModules ?? []).map((stem) => `test_${stem}.py`));
+                    const affected = eligibleItemIds.filter((id) => modules.size === 0 ||
+                        [...modules].some((script) => id.includes(script)) ||
+                        [...newPoints].some((point) => id.includes(point)));
+                    if (affected.length > 0)
+                        eligibleItemIds = affected;
+                }
+                catch {
+                    // no gap plan in this run: execute the full eligible set
+                }
+            }
+            const pytestTargetsRelative = "reports/backend-test-pytest-targets.txt";
+            const pytestTargetsAbsolute = path.join(meta.runDir, pytestTargetsRelative);
+            await writeFile(pytestTargetsAbsolute, `${eligibleItemIds.join("\n")}\n`, "utf8");
+            const pytestTargetsArg = `@\"\${HARNESS_DAG_RUN_DIR}/${pytestTargetsRelative}\"`;
             // Split into short bash -c commands (aligned with markdown-environment).
             // A single ultra-long compound command has been observed on Windows to
             // exit 0xC0000142 (STATUS_DLL_INIT_FAILED) in ~40ms with empty stdout/
@@ -967,8 +1246,10 @@ async function executeBackendTestPipeline(input, meta) {
                 'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
                 'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
                 'echo "STEP=pytest-run"',
-                `echo "- pytestCommand: python -m pytest ${mappedScripts.join(" ")} -v -p no:cacheprovider --html=reports/backend-test.html --self-contained-html" >> "\${DIAG_FILE}"`,
-                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 "\${PYTHON_BIN}" -m pytest ${pytestTargets} -v -p no:cacheprovider --html="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" --self-contained-html`,
+                `echo "- pytestCommand: python -m pytest <${eligibleItemIds.length} eligibility-authorized-items> -v -p no:cacheprovider --html=reports/backend-test.html --self-contained-html" >> "\${DIAG_FILE}"`,
+                `echo "- eligibleItemCount: ${eligibleItemIds.length}" >> "\${DIAG_FILE}"`,
+                `echo "- excludedItemCount: ${executionReadiness.excludedItems.length}" >> "\${DIAG_FILE}"`,
+                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 "\${PYTHON_BIN}" -m pytest ${pytestTargetsArg} -v -p no:cacheprovider --html="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" --self-contained-html`,
                 "STATUS=$?",
                 'printf "%s" "${STATUS}" > "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt"',
                 'echo "- pytestExitCode: ${STATUS}" >> "${DIAG_FILE}"',
@@ -1053,11 +1334,13 @@ async function executeBackendTestPipeline(input, meta) {
                 htmlContent: pytestHtmlContent,
                 pytestExitCode,
             });
-            const cases = await collectBackendTestHumanCaseCatalog(input.cwd);
+            const cases = await collectBackendTestHumanCaseCatalog(input.cwd, backendLayout);
             const caseValidationSummary = await readRequiredRunReport(reportsDir, "backend-md-case-validation.md");
             const caseCoverageSummary = await readAdvisoryRunReport(reportsDir, "backend-test-case-coverage-analysis.md", "Backend Test Case Coverage Analysis");
             const traceabilitySummary = await readRequiredRunReport(reportsDir, "backend-test-traceability.md");
-            const correspondenceSummary = await readAdvisoryRunReport(reportsDir, "backend-test-markdown-pytest-correspondence.md", "Backend Test Markdown → pytest Correspondence");
+            const correspondenceSummaryBase = await readAdvisoryRunReport(reportsDir, "backend-test-markdown-pytest-correspondence.md", "Backend Test Markdown → pytest Correspondence");
+            const eligibilitySummary = await readAdvisoryRunReport(reportsDir, "backend-test-execution-eligibility.md", "Backend Test Execution Eligibility");
+            const correspondenceSummary = `${correspondenceSummaryBase.trim()}\n\n${eligibilitySummary.trim()}\n`;
             const htmlContent = renderBackendTestHtml({
                 title: meta.spec.title,
                 parsed,
@@ -1245,6 +1528,7 @@ async function executeBackendTestPipeline(input, meta) {
                 fromNodeId: "backend-test-execution-envelope",
                 artifactName: "backend-test-execution.json",
                 outputDir: "contracts",
+                allowedTestRoot: backendLayout.testRoot,
             });
             outputs.push(`analysis=${analysis.path}`, `execution=${execution.path}`);
         }
@@ -1360,6 +1644,7 @@ async function executeBackendTestPipeline(input, meta) {
                 artifactName: "backend-test-result-initial.json",
                 outputDir: "contracts",
                 junitRelativePath: "reports/backend-test-initial-junit.xml",
+                testRoot: backendLayout.testRoot,
             });
             outputs.push(...results.map((result) => result.stdout), `result=${artifact.path}`);
         }
@@ -1816,6 +2101,52 @@ async function executeFrontendTestHtmlReport(input, meta) {
         };
     }
 }
+async function executeFrontendTestStandardScenarios(input) {
+    const started = Date.now();
+    try {
+        const result = await copyFrontendTestStandardScenarios({
+            workspaceRoot: input.cwd,
+        });
+        return {
+            ok: true,
+            stdout: JSON.stringify(result),
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+        };
+    }
+}
+async function executeFrontendTestEnvironmentProbe(input) {
+    const started = Date.now();
+    const result = await probeFrontendTestEnvironment({
+        workspaceRoot: input.cwd,
+    });
+    if (result.ok) {
+        return {
+            ok: true,
+            stdout: result.stdout,
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
+    }
+    return {
+        ok: false,
+        stdout: "",
+        stderr: result.stderr,
+        failureCategory: "nonzero-exit",
+        durationMs: Date.now() - started,
+    };
+}
 async function executeFrontendTestEvidenceValidation(input) {
     const started = Date.now();
     try {
@@ -2055,7 +2386,76 @@ async function executeFrontendLintBaseline(input, meta) {
         };
     }
 }
-export async function executeDagShellNode(input, meta) {
+async function writeShellPresetProcessReceipt(input) {
+    await writeDagNodeJsonArtifact(input.runDir, input.nodeId, "process-receipt.json", {
+        schemaVersion: 1,
+        kind: "shell-preset",
+        preset: input.preset,
+        ok: input.ok,
+        durationMs: input.durationMs,
+        steps: input.steps,
+    });
+}
+async function ensureShellPresetProcessReceipt(input) {
+    const receiptPath = path.join(input.runDir, input.nodeId, "process-receipt.json");
+    if (existsSync(receiptPath))
+        return;
+    if (existsSync(path.join(input.runDir, input.nodeId, "shell-command-receipt.json"))) {
+        return;
+    }
+    const detail = input.result.ok ? input.result.stdout : input.result.stderr;
+    await writeShellPresetProcessReceipt({
+        runDir: input.runDir,
+        nodeId: input.nodeId,
+        preset: input.preset,
+        ok: input.result.ok,
+        durationMs: input.result.durationMs,
+        steps: [
+            {
+                id: "run",
+                label: input.preset,
+                ok: input.result.ok,
+                detail: detail?.slice(0, 8 * 1024),
+                durationMs: input.result.durationMs,
+            },
+        ],
+    });
+}
+function namedShellHandler(shell) {
+    if (!shell)
+        return null;
+    const record = shell;
+    for (const key of [
+        "finalWriteSetApprovalGate",
+        "frontendTestStandardScenarios",
+        "frontendTestEnvironmentProbe",
+        "frontendBrowserToolPreflight",
+        "frontendPrewriteGate",
+        "frontendLintBaseline",
+        "frontendVerificationBundle",
+        "frontendReviewContext",
+        "frontendTestCaseChecklist",
+        "frontendTestCaseManifest",
+        "frontendTestEvidenceValidation",
+        "frontendTestResultFinalize",
+        "frontendTestL5Report",
+        "frontendTestHtmlReport",
+        "frontendTestReports",
+        "backendTestPipeline",
+        "jsonArtifactGate",
+        "projectGovernanceGate",
+        "requirementCoverageGate",
+        "verdictGate",
+        "verifyEvidence",
+        "repairArtifactGate",
+        "jacocoCoverage",
+    ]) {
+        if (record[key] != null)
+            return key;
+    }
+    return null;
+}
+async function executeDagShellNodeInner(input, meta) {
     const shell = input.task.shell;
     if (shell?.finalWriteSetApprovalGate) {
         const started = Date.now();
@@ -2094,30 +2494,89 @@ export async function executeDagShellNode(input, meta) {
             };
         }
     }
+    if (shell?.frontendTestStandardScenarios) {
+        return executeFrontendTestStandardScenarios(input);
+    }
+    if (shell?.frontendTestEnvironmentProbe) {
+        return executeFrontendTestEnvironmentProbe(input);
+    }
     if (shell?.frontendBrowserToolPreflight) {
         const started = Date.now();
+        const steps = [];
+        const finish = async (result) => {
+            await writeShellPresetProcessReceipt({
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+                preset: "frontendBrowserToolPreflight",
+                ok: result.ok,
+                durationMs: result.durationMs,
+                steps: steps.length > 0
+                    ? steps
+                    : [
+                        {
+                            id: "run",
+                            label: "浏览器工具能力探测",
+                            ok: result.ok,
+                            detail: result.ok ? result.stdout : result.stderr,
+                            durationMs: result.durationMs,
+                        },
+                    ],
+            });
+            return result;
+        };
         try {
             if (resolvePiBackend() === "cli-only") {
+                steps.push({
+                    id: "pi-backend",
+                    label: "Pi SDK 后端可用",
+                    ok: false,
+                    detail: "CODE_AGENT_PI_BACKEND=cli-only",
+                });
                 throw new Error("browser-command-capability-unavailable: CODE_AGENT_PI_BACKEND=cli-only rejects SDK-only playwright_cli");
             }
+            steps.push({
+                id: "pi-backend",
+                label: "Pi SDK 后端可用",
+                ok: true,
+            });
             const sdkCapability = await checkPiSdkCustomToolCapability(input.cwd);
             if (!sdkCapability.ok) {
+                steps.push({
+                    id: "sdk-custom-tool",
+                    label: "Pi SDK custom-tool 能力",
+                    ok: false,
+                    detail: sdkCapability.detail,
+                });
                 throw new Error(`browser-command-capability-unavailable: ${sdkCapability.detail}`);
             }
+            steps.push({
+                id: "sdk-custom-tool",
+                label: "Pi SDK custom-tool 能力",
+                ok: true,
+            });
             const toolProbe = await createPlaywrightCliTool({
                 repoRoot: input.cwd,
                 runDir: meta.runDir,
                 nodeId: input.task.id,
                 caseId: "frontend-browser-preflight",
                 evidenceDir: "testcase/frontend/evidence/frontend-browser-preflight",
-                // Capability-only registration probe. The tested URL is selected later by
-                // retrieve-frontend-test-context-pi and validated by the environment shell.
                 baseUrl: "http://localhost:5173/",
                 inputRoot: "testcase/frontend/fixtures",
             });
             if (toolProbe.name !== "playwright_cli") {
+                steps.push({
+                    id: "structured-tool",
+                    label: "注册 playwright_cli",
+                    ok: false,
+                    detail: toolProbe.name,
+                });
                 throw new Error("browser-command-capability-unavailable: structured playwright_cli tool registration failed");
             }
+            steps.push({
+                id: "structured-tool",
+                label: "注册 playwright_cli",
+                ok: true,
+            });
             const launcher = resolvePlaywrightCliLauncher(input.cwd);
             const result = await defaultPlaywrightCliCommandRunner({
                 executable: launcher.executable,
@@ -2130,8 +2589,19 @@ export async function executeDagShellNode(input, meta) {
             if (result.exitCode !== 0 ||
                 result.timedOut ||
                 !["open", "close", "find", "snapshot", "click"].every((command) => new RegExp(`\\b${command}\\b`, "i").test(help))) {
+                steps.push({
+                    id: "playwright-cli-help",
+                    label: "playwright-cli --help 合同",
+                    ok: false,
+                    detail: help.slice(0, 8 * 1024),
+                });
                 throw new Error("playwright-cli-contract-incompatible");
             }
+            steps.push({
+                id: "playwright-cli-help",
+                label: "playwright-cli --help 合同",
+                ok: true,
+            });
             const capability = {
                 schemaVersion: 1,
                 status: "ready",
@@ -2142,22 +2612,28 @@ export async function executeDagShellNode(input, meta) {
                 targetUrlAuthority: "retrieve-context-and-environment-probe",
             };
             await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "frontend-browser-capability.json", capability);
-            return {
+            steps.push({
+                id: "capability-artifact",
+                label: "写出 frontend-browser-capability.json",
+                ok: true,
+                detail: JSON.stringify(capability, null, 2),
+            });
+            return await finish({
                 ok: true,
                 stdout: JSON.stringify(capability),
                 stderr: "",
                 failureCategory: "success",
                 durationMs: Date.now() - started,
-            };
+            });
         }
         catch (error) {
-            return {
+            return await finish({
                 ok: false,
                 stdout: "",
                 stderr: `playwright-cli-unavailable: ${error instanceof Error ? error.message : String(error)}`,
                 failureCategory: "tool-policy",
                 durationMs: Date.now() - started,
-            };
+            });
         }
     }
     if (shell?.frontendPrewriteGate) {
@@ -2246,6 +2722,13 @@ export async function executeDagShellNode(input, meta) {
     }
     if (shell?.jsonArtifactGate) {
         const started = Date.now();
+        const backendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
+            ? {
+                testRoot: meta.spec.backendTestLayout.testRoot,
+                markdownRel: meta.spec.backendTestLayout.markdownRel,
+                scriptRel: meta.spec.backendTestLayout.scriptRel,
+            }
+            : undefined);
         try {
             const gate = shell.jsonArtifactGate;
             const sourceNodeId = gate.fallbackFromNodeIds?.length
@@ -2273,6 +2756,7 @@ export async function executeDagShellNode(input, meta) {
                         fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
+                        allowedTestRoot: backendLayout.testRoot,
                     });
                     break;
                 case "backend-test-result-v1":
@@ -2282,6 +2766,7 @@ export async function executeDagShellNode(input, meta) {
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                         junitRelativePath: gate.junitRelativePath,
+                        testRoot: backendLayout.testRoot,
                     });
                     break;
                 case "backend-test-classification-v1":
@@ -2570,6 +3055,7 @@ export async function executeDagShellNode(input, meta) {
     const cwd = resolveShellCwd(input.cwd, shell.cwd);
     const timeoutMs = shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
     const failFast = shell.failFast !== false;
+    const attemptNumber = input.attempt ?? 1;
     const results = [];
     const executedCommandKeys = new Set();
     let beforeStatus;
@@ -2665,8 +3151,8 @@ export async function executeDagShellNode(input, meta) {
             dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
             reportActivity: input.reportActivity,
             outputArtifacts: {
-                stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
-                stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+                stdoutPath: path.join(meta.runDir, input.task.id, `attempt-${attemptNumber}`, "commands", `${commandNumber}.stdout.txt`),
+                stderrPath: path.join(meta.runDir, input.task.id, `attempt-${attemptNumber}`, "commands", `${commandNumber}.stderr.txt`),
             },
         });
         results.push(result);
@@ -2725,6 +3211,7 @@ export async function executeDagShellNode(input, meta) {
         schemaVersion: 1,
         runId: meta.runId,
         nodeId: input.task.id,
+        attempt: attemptNumber,
         workspaceFingerprint: workspaceFingerprint ?? null,
         failFast,
         commands: results.map((result) => ({
@@ -2743,6 +3230,7 @@ export async function executeDagShellNode(input, meta) {
             subchecks: parseCheckRepoSubcheckDurations(result),
         })),
     };
+    await writeDagNodeJsonArtifact(meta.runDir, input.task.id, path.posix.join(`attempt-${attemptNumber}`, "shell-command-receipt.json"), receipt);
     await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "shell-command-receipt.json", receipt);
     const summaryMarkdown = buildShellResultSummaryMarkdown({
         nodeId: input.task.id,
@@ -2794,8 +3282,24 @@ export async function executeDagShellNode(input, meta) {
         stdout: `${recordPrefix}${reuseNote}${aggregate.stdout}`,
         stderr: stderrParts.filter(Boolean).join("\n\n"),
         failureCategory,
+        ...(firstFailure?.failureCategory
+            ? { rawFailureCategory: firstFailure.failureCategory }
+            : {}),
         durationMs: Date.now() - started,
         // extra field consumed by node-execution if supported; also embedded in stdout marker
         ...{ commandResults },
     };
 }
+export async function executeDagShellNode(input, meta) {
+    const handler = namedShellHandler(input.task.shell);
+    const result = await executeDagShellNodeInner(input, meta);
+    if (handler) {
+        await ensureShellPresetProcessReceipt({
+            runDir: meta.runDir,
+            nodeId: input.task.id,
+            preset: handler,
+            result,
+        });
+    }
+    return result;
+}