@tea-agent/loop-agent 0.38.1 → 0.39.0-beta.0

package/dist/executors/pi-sdk-executor.js

@@ -1,6 +1,6 @@
 import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
-import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractAssistantTextFromPiJson, } from "./pi-executor.js";
+import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractPiEventStopReason, extractAssistantTextFromPiJson, } from "./pi-executor.js";
 import { serializeSessionEvent } from "./pi-event-serializer.js";
 import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
 let sdkSessionFactoryOverride;
@@ -44,15 +44,15 @@ export async function resetPiSdkReuseScopeForTests() {
 export function setPiSdkSessionFactoryForTests(factory) {
     sdkSessionFactoryOverride = factory;
 }
-/** Test hook: simulate SDK import success/failure without relying on optionalDependency install state. */
+/** Test hook: simulate SDK import success/failure without relying on installed SDK state. */
 export function setPiSdkImportOverrideForTests(fn) {
     sdkImportOverrideForTests = fn;
 }
-/** Test hook: inject a mock Pi SDK module to exercise resolveSdkSessionFactory without optionalDependency. */
+/** Test hook: inject a mock Pi SDK module to exercise resolveSdkSessionFactory without loading the real SDK. */
 export function setPiSdkModuleOverrideForTests(fn) {
     sdkModuleOverrideForTests = fn;
 }
-/** Check whether the Pi SDK optional dependency satisfies the 0.80.10 runtime contract. */
+/** Check whether the Pi SDK runtime dependency satisfies the 0.83.0 runtime contract. */
 export async function checkPiSdkAvailability(_repoRoot) {
     if (sdkSessionFactoryOverride) {
         return { ok: true, detail: "pi SDK session factory override active" };
@@ -68,10 +68,10 @@ export async function checkPiSdkAvailability(_repoRoot) {
             typeof ModelRuntime?.create !== "function") {
             return {
                 ok: false,
-                detail: "pi SDK incompatible: requires createAgentSession, getAgentDir, and ModelRuntime.create (0.80.10 contract)",
+                detail: "pi SDK incompatible: requires createAgentSession, getAgentDir, and ModelRuntime.create (0.83.0 contract)",
             };
         }
-        return { ok: true, detail: "pi SDK 0.80.10 contract available" };
+        return { ok: true, detail: "pi SDK 0.83.0 contract available" };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -404,25 +404,6 @@ function extractSdkUsageSample(event) {
     const responseKey = responseKeyCandidates.find((value) => typeof value === "string" && value.length > 0);
     return responseKey ? { responseKey, tokens } : { tokens };
 }
-/** Extract a non-empty stop reason from a terminal SDK event.
- * Probes multiple field shapes across SDK versions so a missing field fails
- * open (undefined) rather than misclassifying an attempt. */
-function readStopReason(event) {
-    const message = isRecord(event.message) ? event.message : undefined;
-    const candidates = [
-        message?.stop_reason,
-        message?.stopReason,
-        event.stopReason,
-        event.stop_reason,
-    ];
-    for (const candidate of candidates) {
-        if (typeof candidate === "string" &&
-            candidate.trim().length > 0) {
-            return candidate.trim();
-        }
-    }
-    return undefined;
-}
 function aggregateSdkTokenUsage(samples) {
     const identified = new Map();
     let anonymousMaximum = 0;
@@ -494,7 +475,7 @@ export async function executeSingleSdkAttempt(options) {
             type === "message_end" ||
             type === "agent_end" ||
             type === "agent_settled") {
-            const candidate = readStopReason(event);
+            const candidate = extractPiEventStopReason(event);
             if (candidate)
                 stopReason = candidate;
         }

package/dist/executors/shell-executor.js

@@ -27,11 +27,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 +50,7 @@ async function runBackendScenarioParamPreflight(input) {
         phase: "initial",
         repairAttempt: 0,
         strictScenarioParamGate: input.strictScenarioParamGate,
+        layout: input.layout,
     });
     const initialArtifacts = await writeBackendScenarioParamArtifacts({
         runDir: input.runDir,
@@ -73,6 +76,7 @@ async function runBackendScenarioParamPreflight(input) {
             phase: "final",
             repairAttempt: 1,
             strictScenarioParamGate: input.strictScenarioParamGate,
+            layout: input.layout,
         });
         finalFacts = reassessed.facts;
         finalMarkdown = reassessed.markdown;
@@ -492,11 +496,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 +637,8 @@ async function executeBackendTestPipeline(input, meta) {
                     environmentMarkdown,
                     requiredRequirementIds,
                     sourceBinding: meta.spec.sourceBinding,
+                    layout: backendLayout,
+                    sharedSetup: meta.spec.backendTestSharedSetup ?? null,
                 });
             }
             catch (error) {
@@ -583,6 +692,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 +700,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 +733,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 +745,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 +759,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 +797,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 +807,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 +877,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 +920,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 +944,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 +1005,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 +1041,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 +1104,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 +1206,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 +1294,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 +1488,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 +1604,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}`);
         }
@@ -2246,6 +2491,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 +2525,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 +2535,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":

package/dist/governance/manifest-types.js

@@ -78,8 +78,6 @@ export const executorManifestSchema = z
     LOW: executorTierModelSchema.optional(),
     MED: executorTierModelSchema.optional(),
     HIGH: executorTierModelSchema.optional(),
-    /** Console 模型矩阵下拉专用列表；仅供 UI 使用，不参与 DAG 模型路由。 */
-    modelOptions: z.array(z.string().min(1)).optional(),
 })
     .strict();
 export const workflowPolicyProfileNameSchema = z.enum([