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

package/dist/executors/shell-executor.js

@@ -0,0 +1,3055 @@
+import { spawn } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { writeDagNodeJsonArtifact, writeDagNodeTextArtifact, } from "../infrastructure/harness/artifact-store.js";
+import { captureWorkspaceCheckpoint } from "../workflows/dag/workspace-checkpoint.js";
+import { truncateOutput } from "../shared/output-truncation.js";
+import { processTreeSpawnOptions, terminateProcessTree, } from "./process-tree.js";
+import { createPlaywrightCliTool, defaultPlaywrightCliCommandRunner, } from "./pi-playwright-cli-tool.js";
+import { resolvePiBackend } from "./pi-executor.js";
+import { checkPiSdkCustomToolCapability } from "./pi-sdk-executor.js";
+import { resolvePlaywrightCliLauncher } from "./playwright-cli-launcher.js";
+import { buildRequirementCoverageGateShellCommand, expandShellPreset, buildVerdictGateShellCommand, } from "./shell-presets.js";
+import { materializeBackendTestAnalysisContract } from "../workflows/dag/backend-test-analysis-contract.js";
+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 { 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";
+import { renderFrontendTestHtmlReport } from "../workflows/dag/frontend-test-html-report.js";
+import { formatFrontendVerificationTraceStdout, runFrontendVerificationTraceGate, } from "../workflows/dag/frontend-verification-trace.js";
+import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "../workflows/dag/frontend-worktree-diff.js";
+import { formatFrontendFailureAssessStdout, formatFrontendRepairContractStdout, runFrontendFailureAssessGate, runFrontendRepairContractGate, } from "../workflows/dag/frontend-repair.js";
+import { formatFrontendPrewriteGateStdout, runFrontendPrewriteGate, } from "../workflows/dag/frontend-prewrite-gate.js";
+import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from "../workflows/dag/frontend-review-context.js";
+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, 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, 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";
+import { pathsChangedDuringRun, readGitStatusPorcelain, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
+import { parseAndValidateFinalWriteSetApproval, } from "../workflows/dag/node-execution.js";
+import { buildShellProcessEnv } from "./shell-verification.js";
+import { readRunState } from "../workflows/dag/run-store.js";
+import { readProjectGovernanceContext } from "../workflows/dag/project-governance-context.js";
+import { assertMavenPlanFresh, MavenPlanStaleError, } from "../verification/maven/index.js";
+async function runBackendScenarioParamPreflight(input) {
+    const outputs = [];
+    const initial = await assessBackendScenarioParamConsistency({
+        workspaceRoot: input.workspaceRoot,
+        phase: "initial",
+        repairAttempt: 0,
+        strictScenarioParamGate: input.strictScenarioParamGate,
+        layout: input.layout,
+    });
+    const initialArtifacts = await writeBackendScenarioParamArtifacts({
+        runDir: input.runDir,
+        facts: initial.facts,
+        markdown: initial.markdown,
+    });
+    outputs.push(`scenarioParamInitial=${initialArtifacts.reportPath}`);
+    let finalFacts;
+    let finalMarkdown;
+    if (initial.facts.repairEligible) {
+        const repair = await applyDeterministicScenarioParamRepairs({
+            workspaceRoot: input.workspaceRoot,
+            facts: initial.facts,
+        });
+        const auditPath = await writeScenarioParamRepairAudit({
+            runDir: input.runDir,
+            audit: repair.audit,
+            changedFiles: repair.changedFiles,
+        });
+        outputs.push(`scenarioParamRepairAudit=${auditPath}`, `scenarioParamRepaired=${repair.repaired.join(",") || "(none)"}`);
+        const reassessed = await assessBackendScenarioParamConsistency({
+            workspaceRoot: input.workspaceRoot,
+            phase: "final",
+            repairAttempt: 1,
+            strictScenarioParamGate: input.strictScenarioParamGate,
+            layout: input.layout,
+        });
+        finalFacts = reassessed.facts;
+        finalMarkdown = reassessed.markdown;
+    }
+    else {
+        finalFacts = { ...initial.facts, phase: "final", repairAttempt: 0, repairEligible: false };
+        finalMarkdown = initial.markdown.replace("Phase: initial", "Phase: final");
+    }
+    const finalArtifacts = await writeBackendScenarioParamArtifacts({
+        runDir: input.runDir,
+        facts: finalFacts,
+        markdown: finalMarkdown,
+    });
+    outputs.push(`scenarioParamFinal=${finalArtifacts.reportPath}`, `scenarioParamStatus=${finalFacts.overallStatus}`);
+    if (input.strictScenarioParamGate && ["FAIL", "UNAVAILABLE"].includes(finalFacts.overallStatus)) {
+        throw new Error(`backend-test strict scenario-param gate blocked ${finalFacts.overallStatus} before collection`);
+    }
+    return { facts: finalFacts, outputs };
+}
+/** In-memory same-run success cache. Never shared across runIds. */
+const sameRunShellCommandCaches = new Map();
+function shellCommandCacheKey(runId, workspaceFingerprint, contractKey) {
+    return `${runId}::${workspaceFingerprint}::${contractKey}`;
+}
+function buildShellCommandContractKey(input) {
+    const environment = Object.fromEntries((input.envAllowlist ?? []).sort().map((name) => [name, process.env[name] ?? null]));
+    return JSON.stringify({
+        cwd: input.cwd,
+        timeoutMs: input.timeoutMs,
+        environment,
+        failFast: input.failFast,
+        nonZeroExitPolicy: input.nonZeroExitPolicy ?? "fail",
+        controllerInput: input.controllerInput ?? null,
+    });
+}
+export function clearSameRunShellCommandCachesForTests() {
+    sameRunShellCommandCaches.clear();
+}
+function shouldReuseSuccessfulShellCommands(shell) {
+    return shell.verifyEvidence?.phase === "intermediate" || shell.verifyEvidence?.phase === "final";
+}
+const DEFAULT_SHELL_TIMEOUT_MS = 300_000;
+const SUMMARY_STDOUT_MAX = 4_000;
+const SUMMARY_STDERR_MAX = 2_000;
+const NODE_STDOUT_MAX = 12_000;
+const NODE_STDERR_MAX = 8_000;
+const MAX_BUFFERED_OUTPUT_BYTES = 64 * 1024;
+function resolveBashExecutable() {
+    const envCandidate = process.env.LOOP_AGENT_BASH ?? process.env.GIT_BASH;
+    if (envCandidate && existsSync(envCandidate))
+        return envCandidate;
+    if (process.platform !== "win32")
+        return envCandidate || "bash";
+    const candidates = [
+        path.join(process.env.ProgramFiles ?? "C:\\Program Files", "Git", "bin", "bash.exe"),
+        path.join(process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)", "Git", "bin", "bash.exe"),
+        path.join(process.env.LocalAppData ?? "", "Programs", "Git", "bin", "bash.exe"),
+    ].filter(Boolean);
+    return (candidates.find((candidate) => existsSync(candidate)) ??
+        envCandidate ??
+        "bash");
+}
+/** POSIX-style runDir for bash `${HARNESS_DAG_RUN_DIR}` expansions on Windows. */
+function normalizeHarnessDagRunDir(runDir) {
+    return runDir.replaceAll(path.sep, "/");
+}
+const BACKEND_TEST_EXECUTE_DIAGNOSTICS_REL = "reports/backend-test-execute-diagnostics.md";
+/**
+ * Write diagnostics *before* any bash spawn so Windows STATUS_DLL_INIT_FAILED
+ * (0xC0000142) / empty-shell-output failures still leave an auditable file.
+ * Shell steps append under `## shell-steps`; they must not overwrite this head.
+ */
+async function writeBackendTestExecuteDiagnosticsPreSpawn(input) {
+    const harnessDagRunDir = normalizeHarnessDagRunDir(input.runDir);
+    if (!harnessDagRunDir.trim()) {
+        throw new Error("HARNESS_DAG_RUN_DIR would be empty; refusing backend-test execute (would write under /reports)");
+    }
+    const reportsDir = path.join(input.runDir, "reports");
+    await mkdir(reportsDir, { recursive: true });
+    const diagnosticsPath = path.join(reportsDir, "backend-test-execute-diagnostics.md");
+    const lines = [
+        "# Backend Test Execute Diagnostics",
+        "",
+        "## pre-spawn",
+        "",
+        `- phase: pre-spawn`,
+        `- startedAt: ${new Date().toISOString()}`,
+        `- cwd: ${input.cwd}`,
+        `- runId: ${input.runId}`,
+        `- runDir: ${input.runDir}`,
+        `- HARNESS_DAG_RUN_DIR: ${harnessDagRunDir}`,
+        `- bashExecutable: ${resolveBashExecutable()}`,
+        `- platform: ${process.platform}`,
+        `- mappedScriptCount: ${input.mappedScripts.length}`,
+        "- mappedScripts:",
+        ...(input.mappedScripts.length > 0
+            ? input.mappedScripts.map((script) => `  - ${script}`)
+            : ["  - <none>"]),
+        `- commandPlanCount: ${input.commandPlan.length}`,
+        "- commandPlan:",
+        ...input.commandPlan.map((label, index) => `  - ${index + 1}. ${label}`),
+        "",
+        "## shell-steps",
+        "",
+        "_Shell commands append below. If this section stays empty, bash never ran successfully._",
+        "",
+    ];
+    await writeFile(diagnosticsPath, `${lines.join("\n")}\n`, "utf8");
+    return { diagnosticsPath, harnessDagRunDir };
+}
+function isWithinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+export function resolveShellCwd(root, requestedCwd) {
+    const resolved = requestedCwd ? path.resolve(root, requestedCwd) : root;
+    if (!isWithinRoot(root, resolved)) {
+        throw new Error(`shell cwd must stay within DAG cwd: ${requestedCwd}`);
+    }
+    return resolved;
+}
+async function resolveJsonArtifactSourceNodeId(input) {
+    const candidates = [
+        input.fromNodeId,
+        ...new Set((input.fallbackFromNodeIds ?? []).filter((nodeId) => nodeId !== input.fromNodeId)),
+    ];
+    for (const nodeId of candidates) {
+        try {
+            await stat(path.join(input.runDir, `${nodeId}.json`));
+            return nodeId;
+        }
+        catch (error) {
+            if (error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error(`missing jsonArtifactGate node output (tried: ${candidates.join(", ")})`);
+}
+/** Preset commands first, then explicit shell.commands, then verdictGate (deterministic ordering). */
+export function resolveShellCommands(shell) {
+    const fromPreset = shell.preset ? expandShellPreset(shell.preset) : [];
+    const explicit = (shell.commands ?? []).filter((command) => command.trim().length > 0);
+    const fromVerdictGate = shell.verdictGate
+        ? [buildVerdictGateShellCommand(shell.verdictGate)]
+        : [];
+    const fromRequirementCoverageGate = shell.requirementCoverageGate
+        ? [buildRequirementCoverageGateShellCommand(shell.requirementCoverageGate)]
+        : [];
+    return [
+        ...fromPreset,
+        ...explicit,
+        ...fromVerdictGate,
+        ...fromRequirementCoverageGate,
+    ];
+}
+export async function executeShellCommand(input) {
+    return new Promise((resolve) => {
+        const startedAt = Date.now();
+        const startedAtIso = new Date(startedAt).toISOString();
+        let lastOutputActivityAt = 0;
+        const reportOutputActivity = () => {
+            const now = Date.now();
+            if (now - lastOutputActivityAt < 500)
+                return;
+            lastOutputActivityAt = now;
+            input.reportActivity?.({ attempt: 1, kind: "output", at: new Date(now).toISOString() });
+        };
+        const injectedEnv = input.dagRunMeta
+            ? {
+                // Git Bash treats backslashes as escape characters inside double
+                // quotes. On Windows, path.join() produces backslash runDirs like
+                // D:\\...\\active\\<runId>, which corrupt "${HARNESS_DAG_RUN_DIR}/..."
+                // expansions. Normalize to POSIX separators so bash sees a stable
+                // path regardless of host platform.
+                HARNESS_DAG_RUN_DIR: input.dagRunMeta.runDir.replaceAll(path.sep, "/"),
+                HARNESS_DAG_RUN_ID: input.dagRunMeta.runId,
+            }
+            : undefined;
+        const child = spawn(resolveBashExecutable(), ["-c", input.command], {
+            cwd: input.cwd,
+            env: buildShellProcessEnv(input.envAllowlist, injectedEnv),
+            ...processTreeSpawnOptions(),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = createBoundedOutput();
+        let stderr = createBoundedOutput();
+        let timedOut = false;
+        let settled = false;
+        let timeoutHandle;
+        let sigkillHandle;
+        function finish(result) {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (sigkillHandle)
+                clearTimeout(sigkillHandle);
+            resolve({
+                command: input.command,
+                cwd: input.cwd,
+                durationMs: Date.now() - startedAt,
+                wallDurationMs: Date.now() - startedAt,
+                startedAt: startedAtIso,
+                finishedAt: new Date().toISOString(),
+                stdout: formatBoundedOutput(stdout),
+                stdoutBytes: stdout.bytes,
+                stdoutTruncated: stdout.truncated,
+                stderr: formatBoundedOutput(stderr),
+                stderrBytes: stderr.bytes,
+                stderrTruncated: stderr.truncated,
+                ...(input.outputArtifacts
+                    ? {
+                        stdoutArtifactPath: input.outputArtifacts.stdoutPath,
+                        stderrArtifactPath: input.outputArtifacts.stderrPath,
+                    }
+                    : {}),
+                timedOut,
+                ...result,
+            });
+        }
+        child.stdout.setEncoding("utf-8");
+        child.stderr.setEncoding("utf-8");
+        initializeOutputArtifacts(input.outputArtifacts);
+        child.stdout.on("data", (chunk) => {
+            stdout = appendBoundedOutput(stdout, chunk);
+            appendOutputArtifact(input.outputArtifacts?.stdoutPath, chunk);
+            reportOutputActivity();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr = appendBoundedOutput(stderr, chunk);
+            appendOutputArtifact(input.outputArtifacts?.stderrPath, chunk);
+            reportOutputActivity();
+        });
+        child.on("error", (error) => {
+            stderr = appendBoundedOutput(stderr, `${stderr.text ? "\n" : ""}${error.message}`);
+            appendOutputArtifact(input.outputArtifacts?.stderrPath, error.message);
+            finish({
+                exitCode: null,
+                failureCategory: "spawn-error",
+                ok: false,
+            });
+        });
+        child.on("close", (code) => {
+            let failureCategory = "nonzero-exit";
+            if (timedOut) {
+                failureCategory = "timeout";
+            }
+            else if (code === 0) {
+                failureCategory = "success";
+            }
+            finish({
+                exitCode: code,
+                failureCategory,
+                ok: code === 0 && !timedOut,
+            });
+        });
+        if (input.timeoutMs > 0) {
+            timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                terminateProcessTree(child, "SIGTERM");
+                sigkillHandle = setTimeout(() => {
+                    if (child.exitCode === null) {
+                        terminateProcessTree(child, "SIGKILL");
+                    }
+                }, 5_000);
+            }, input.timeoutMs);
+        }
+    });
+}
+function createBoundedOutput() {
+    return { bytes: 0, text: "", truncated: false };
+}
+function appendBoundedOutput(current, chunk) {
+    const bytes = current.bytes + Buffer.byteLength(chunk);
+    const combined = current.text + chunk;
+    if (Buffer.byteLength(combined) <= MAX_BUFFERED_OUTPUT_BYTES) {
+        return { bytes, text: combined, truncated: current.truncated };
+    }
+    const tail = Buffer.from(combined)
+        .subarray(-MAX_BUFFERED_OUTPUT_BYTES)
+        .toString("utf-8")
+        .replace(/^\uFFFD/, "");
+    return { bytes, text: tail, truncated: true };
+}
+function formatBoundedOutput(output) {
+    return output.truncated ? `${output.text}\n...[truncated]` : output.text;
+}
+function initializeOutputArtifacts(paths) {
+    if (!paths)
+        return;
+    try {
+        mkdirSync(path.dirname(paths.stdoutPath), { recursive: true });
+        writeFileSync(paths.stdoutPath, "", "utf-8");
+        writeFileSync(paths.stderrPath, "", "utf-8");
+    }
+    catch {
+        // Artifact persistence is best-effort; the bounded result remains available.
+    }
+}
+function appendOutputArtifact(filePath, chunk) {
+    if (!filePath)
+        return;
+    try {
+        appendFileSync(filePath, chunk, "utf-8");
+    }
+    catch {
+        // Keep command execution independent from a transient artifact write failure.
+    }
+}
+function summarizeCommandResults(results) {
+    const stdout = results
+        .map((result) => [`$ ${result.command}`, result.stdout.trim()].filter(Boolean).join("\n"))
+        .join("\n\n");
+    const stderr = results
+        .filter((result) => result.stderr.trim().length > 0)
+        .map((result) => [`$ ${result.command}`, result.stderr.trim()].join("\n"))
+        .join("\n\n");
+    return {
+        stdout: truncateOutput(stdout, NODE_STDOUT_MAX).text,
+        stderr: truncateOutput(stderr, NODE_STDERR_MAX).text,
+    };
+}
+function parseCheckRepoSubcheckDurations(result) {
+    if (!/scripts\/check-repo\.sh/.test(result.command))
+        return [];
+    const durations = [];
+    for (const line of `${result.stdout}\n${result.stderr}`.split(/\r?\n/)) {
+        const match = /^CHECK_REPO_SUBCHECK_END name=(\S+) status=(success|failed) durationMs=(\d+)$/.exec(line.trim());
+        if (match)
+            durations.push({ name: match[1], status: match[2], durationMs: Number(match[3]) });
+    }
+    return durations;
+}
+export function buildShellResultSummaryMarkdown(input) {
+    const lines = [
+        "# Shell execution summary",
+        "",
+        "## Run metadata",
+        "",
+        "| Field | Value |",
+        "|-------|-------|",
+        `| dagRunId | ${input.runId} |`,
+        `| dagNodeId | ${input.nodeId} |`,
+        `| cwd | ${input.rootCwd} |`,
+        `| commandCount | ${input.results.length} |`,
+        "",
+        "## Commands",
+        "",
+        "| # | ok | exitCode | failureCategory | startedAt | finishedAt | wallDurationMs | executionDurationMs | reused | cwd | command |",
+        "|---|----|----------|-----------------|-----------|------------|----------------|---------------------|--------|-----|---------|",
+    ];
+    input.results.forEach((result, index) => {
+        lines.push(`| ${index + 1} | ${result.ok} | ${result.exitCode ?? "null"} | ${result.failureCategory} | ${result.startedAt ?? "(unknown)"} | ${result.finishedAt ?? "(unknown)"} | ${result.wallDurationMs ?? result.durationMs} | ${result.executionDurationMs ?? result.durationMs} | ${result.reused === true} | ${result.cwd} | ${result.command.replace(/\|/g, "\\|")} |`);
+    });
+    if (input.writeGuardViolations && input.writeGuardViolations.length > 0) {
+        lines.push("", "## Write guard violations", "");
+        for (const violation of input.writeGuardViolations) {
+            lines.push(`- ${violation}`);
+        }
+    }
+    for (const [index, result] of input.results.entries()) {
+        const stdout = truncateOutput(result.stdout, SUMMARY_STDOUT_MAX);
+        const stderr = truncateOutput(result.stderr, SUMMARY_STDERR_MAX);
+        lines.push("", `## Command ${index + 1}: ${result.command}`, "", "### stdout", "", "```text", stdout.text, "```");
+        if (stdout.truncated)
+            lines.push("", "_(stdout truncated)_");
+        if (result.stdoutArtifactPath) {
+            lines.push("", `Full stdout artifact: ${result.stdoutArtifactPath}`);
+        }
+        if (stderr.text.trim()) {
+            lines.push("", "### stderr", "", "```text", stderr.text, "```");
+            if (stderr.truncated)
+                lines.push("", "_(stderr truncated)_");
+        }
+        if (result.stderrArtifactPath) {
+            lines.push("", `Full stderr artifact: ${result.stderrArtifactPath}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function runShellWriteGuard(input) {
+    const afterStatus = await readGitStatusPorcelain(input.rootCwd);
+    const beforeSnapshot = snapshotGitStatusPorcelain(input.beforeStatus);
+    const afterSnapshot = snapshotGitStatusPorcelain(afterStatus);
+    const changedPaths = pathsChangedDuringRun(beforeSnapshot, afterSnapshot);
+    return validateShellWriteGuard({
+        changedPaths,
+        writePolicy: input.task.writePolicy,
+        writeSet: input.task.writeSet,
+        allowedPaths: input.task.allowedPaths,
+        forbiddenPaths: input.task.forbiddenPaths,
+    });
+}
+async function readRequiredRunReport(reportsDir, filename) {
+    try {
+        return await readFile(path.join(reportsDir, filename), "utf8");
+    }
+    catch {
+        throw new Error(`missing required upstream report: reports/${filename}`);
+    }
+}
+async function readAdvisoryRunReport(reportsDir, filename, title) {
+    try {
+        return await readFile(path.join(reportsDir, filename), "utf8");
+    }
+    catch {
+        return `# ${title}\n\n## Status\n\nUNAVAILABLE\n\n## Findings\n\n- Missing advisory upstream report: reports/${filename}\n`;
+    }
+}
+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 === "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);
+                return {
+                    ok: false,
+                    stdout: results.map((result) => result.stdout).join("\n"),
+                    stderr: failure.stderr,
+                    failureCategory: failure.failureCategory,
+                    durationMs: Date.now() - started,
+                };
+            }
+            const environment = await inspectBackendTestEnvironment({
+                workspaceRoot: input.cwd,
+                pythonVersion: results[0]?.stdout ?? "unknown",
+                pytestVersion: results[1]?.stdout ?? "unknown",
+                pytestHelp: results[2]?.stdout ?? "",
+            });
+            const reportPath = await writeRunReport(meta.runDir, "backend-test-environment.md", environment.markdown);
+            outputs.push(`environment=${reportPath}`, environment.markdown);
+        }
+        else if (pipeline === "markdown-cases") {
+            const environmentMarkdown = await readFile(path.join(meta.runDir, "reports", "backend-test-environment.md"), "utf8");
+            const requiredRequirementIds = requiredBackendMarkdownCaseAcIds([
+                meta.spec.objective ?? "",
+                ...(meta.spec.successCriteria ?? []),
+            ]);
+            let report;
+            try {
+                report = await validateBackendMarkdownCases({
+                    workspaceRoot: input.cwd,
+                    environmentMarkdown,
+                    requiredRequirementIds,
+                    sourceBinding: meta.spec.sourceBinding,
+                    layout: backendLayout,
+                    sharedSetup: meta.spec.backendTestSharedSetup ?? null,
+                });
+            }
+            catch (error) {
+                report = `# Backend Markdown Case Validation\n\n## Status\n\nFAIL\n\n## Findings\n\n- Validator could not complete: ${error instanceof Error ? error.message : String(error)}\n`;
+            }
+            const reportPath = await writeRunReport(meta.runDir, "backend-md-case-validation.md", report);
+            outputs.push(`caseValidation=${reportPath}`, report);
+            if (hasBlockingBackendMarkdownSafetyFindings(report)) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: "backend Markdown safety gate blocked: secret-shaped values detected",
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            if (hasBlockingBackendMarkdownModuleStemFindings(report)) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: "backend Markdown module stem gate blocked: priority-only-module-stem",
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            const sourceBinding = meta.spec.sourceBinding;
+            if (!sourceBinding) {
+                const coverage = "# Backend Test Case Coverage Analysis\n\n## Status\n\nUNAVAILABLE\n\n## Findings\n\n- Coverage analysis requires spec.sourceBinding; node 4 and node 7 fail closed on the same task/source binding contract.\n";
+                const coveragePath = await writeRunReport(meta.runDir, "backend-test-case-coverage-analysis.md", coverage);
+                outputs.push(`caseCoverage=${coveragePath}`, coverage);
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n\n"),
+                    stderr: "backend-test markdown-cases requires spec.sourceBinding",
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            const normalizedBinding = {
+                taskId: sourceBinding.taskId,
+                requirementPath: sourceBinding.sources.find((s) => s.kind === "requirement")?.path ??
+                    "source/requirement.md",
+                requirementSha256: sourceBinding.sources.find((s) => s.kind === "requirement")?.sha256 ??
+                    "0".repeat(64),
+                referencePaths: sourceBinding.sources
+                    .filter((s) => s.kind === "reference")
+                    .map((s) => s.path),
+                requirementIds: sourceBinding.requirementIds,
+            };
+            try {
+                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");
+                await mkdir(contractsDir, { recursive: true });
+                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)/.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);
+                const coverage = `# Backend Test Case Coverage Analysis\n\n## Status\n\nUNAVAILABLE\n\n## Findings\n\n- Coverage analysis crashed and is treated as an infrastructure failure: ${message}\n`;
+                const coveragePath = await writeRunReport(meta.runDir, "backend-test-case-coverage-analysis.md", coverage);
+                outputs.push(`caseCoverage=${coveragePath}`, coverage);
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n\n"),
+                    stderr: `backend-test coverage analysis crashed: ${message}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
+        else if (pipeline === "markdown-collection-assess") {
+            const resolution = await resolveBackendTestMappedPytestScripts(input.cwd, backendLayout);
+            let facts;
+            const preflightInventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false, layout: backendLayout });
+            const priorityOnlyFacts = assessPriorityOnlyBackendPytestModules({
+                phase: "initial",
+                mappedScripts: resolution.expectedScripts,
+                inventory: preflightInventory,
+            });
+            if (priorityOnlyFacts) {
+                facts = priorityOnlyFacts;
+            }
+            else if (resolution.missingScripts.length > 0) {
+                const inventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false, layout: backendLayout });
+                facts = assessMissingBackendPytestScripts({
+                    mappedScripts: resolution.expectedScripts,
+                    existingMappedScripts: resolution.existingScripts,
+                    missingMappedScripts: resolution.missingScripts,
+                    assetFiles: inventory.assetFiles,
+                    inputHashes: inventory.inputHashes,
+                });
+            }
+            else {
+                const mappedScripts = resolution.existingScripts;
+                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, { 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}`;
+                const [result] = await executePipelineCommands(input, meta, [command]);
+                if (!result)
+                    throw new Error("backend pytest collection command did not produce a result");
+                if (["spawn-error", "timeout", "termination-unconfirmed"].includes(result.failureCategory ?? "")) {
+                    return {
+                        ok: false,
+                        stdout: result.stdout,
+                        stderr: result.stderr || "backend pytest collection could not start",
+                        failureCategory: result.failureCategory,
+                        durationMs: Date.now() - started,
+                    };
+                }
+                let fixtureResolution;
+                if ((result.exitCode ?? 2) === 0) {
+                    const fixtureCommand = `PYTHONDONTWRITEBYTECODE=1 python -m pytest --setup-plan -q -p no:cacheprovider ${targets}`;
+                    const [fixtureResult] = await executePipelineCommands(input, meta, [fixtureCommand]);
+                    if (!fixtureResult)
+                        throw new Error("backend pytest fixture-resolution command did not produce a result");
+                    if (["spawn-error", "timeout", "termination-unconfirmed"].includes(fixtureResult.failureCategory ?? "")) {
+                        return {
+                            ok: false,
+                            stdout: fixtureResult.stdout,
+                            stderr: fixtureResult.stderr || "backend pytest fixture resolution could not start",
+                            failureCategory: fixtureResult.failureCategory,
+                            durationMs: Date.now() - started,
+                        };
+                    }
+                    fixtureResolution = { exitCode: fixtureResult.exitCode ?? 2, stdout: fixtureResult.stdout, stderr: fixtureResult.stderr };
+                }
+                facts = assessBackendPytestCollection({
+                    layout: backendLayout,
+                    phase: "initial",
+                    mappedScripts,
+                    inventory,
+                    exitCode: result.exitCode ?? 2,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    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",
+                facts,
+            });
+            outputs.push(`collectionFacts=${artifacts.factsPath}`, `collectionReport=${artifacts.reportPath}`);
+            return {
+                ok: true,
+                stdout: JSON.stringify({
+                    status: facts.status,
+                    repairEligible: facts.repairEligible,
+                    collectionAttempted: facts.collectionAttempted,
+                    pytestExitCode: facts.pytestExitCode,
+                    fixtureResolutionStatus: facts.fixtureResolutionStatus,
+                    collectedItemCount: facts.collectedItemCount,
+                    missingMappedScripts: facts.missingMappedScripts,
+                    repairPaths: facts.repairPaths,
+                    factsPath: "contracts/backend-test-pytest-collection-initial.json",
+                }),
+                stderr: "",
+                durationMs: Date.now() - started,
+            };
+        }
+        else if (pipeline === "markdown-collection-effective") {
+            const initial = await readBackendPytestCollectionFacts(path.join(meta.runDir, "contracts", "backend-test-pytest-collection-initial.json"));
+            let effective;
+            if (initial.status === "PASS") {
+                effective = await materializeEffectiveBackendPytestCollection({
+                    workspaceRoot: input.cwd,
+                    initial,
+                });
+            }
+            else if (initial.status === "REPAIRABLE") {
+                const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
+                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, { 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}`;
+                const [result] = await executePipelineCommands(input, meta, [command]);
+                if (!result)
+                    throw new Error("backend pytest final collection command did not produce a result");
+                if (["spawn-error", "timeout", "termination-unconfirmed"].includes(result.failureCategory ?? "")) {
+                    return {
+                        ok: false,
+                        stdout: result.stdout,
+                        stderr: result.stderr ||
+                            "backend pytest final collection could not start",
+                        failureCategory: result.failureCategory,
+                        durationMs: Date.now() - started,
+                    };
+                }
+                let fixtureResolution;
+                if ((result.exitCode ?? 2) === 0) {
+                    const fixtureCommand = `PYTHONDONTWRITEBYTECODE=1 python -m pytest --setup-plan -q -p no:cacheprovider ${targets}`;
+                    const [fixtureResult] = await executePipelineCommands(input, meta, [fixtureCommand]);
+                    if (!fixtureResult)
+                        throw new Error("backend pytest final fixture-resolution command did not produce a result");
+                    if (["spawn-error", "timeout", "termination-unconfirmed"].includes(fixtureResult.failureCategory ?? "")) {
+                        return {
+                            ok: false,
+                            stdout: fixtureResult.stdout,
+                            stderr: fixtureResult.stderr || "backend pytest final fixture resolution could not start",
+                            failureCategory: fixtureResult.failureCategory,
+                            durationMs: Date.now() - started,
+                        };
+                    }
+                    fixtureResolution = { exitCode: fixtureResult.exitCode ?? 2, stdout: fixtureResult.stdout, stderr: fixtureResult.stderr };
+                }
+                const finalFacts = assessBackendPytestCollection({
+                    layout: backendLayout,
+                    phase: "final",
+                    mappedScripts,
+                    inventory,
+                    exitCode: result.exitCode ?? 2,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    fixtureResolution,
+                });
+                effective = await materializeEffectiveBackendPytestCollection({
+                    workspaceRoot: input.cwd,
+                    initial,
+                    final: finalFacts,
+                });
+            }
+            else {
+                throw new Error("backend pytest collection is blocked and does not authorize repair");
+            }
+            const artifacts = await writeBackendPytestCollectionArtifacts({
+                runDir: meta.runDir,
+                stem: "effective",
+                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,
+                stdout: JSON.stringify({
+                    status: effective.status,
+                    collectionSource: effective.collectionSource,
+                    repairAttempt: effective.repairAttempt,
+                    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,
+                }),
+                stderr: "",
+                durationMs: Date.now() - started,
+            };
+        }
+        else if (pipeline === "markdown-traceability") {
+            let report;
+            try {
+                report = await validateBackendMarkdownTraceability(input.cwd);
+            }
+            catch (error) {
+                report = `# Backend Test Traceability\n\n## Status\n\nFAIL\n\n## Findings\n\n- Traceability validation could not complete: ${error instanceof Error ? error.message : String(error)}\n`;
+            }
+            const reportPath = await writeRunReport(meta.runDir, "backend-test-traceability.md", report);
+            outputs.push(`traceability=${reportPath}`, report);
+            const sourceBinding = meta.spec.sourceBinding;
+            if (!sourceBinding) {
+                const correspondence = "# Backend Test Markdown → pytest Correspondence\n\n## Status\n\nUNAVAILABLE\n\n## Findings\n\n- Correspondence analysis requires spec.sourceBinding; nodes 4, 6 and 7 fail closed on the same task/source binding contract.\n";
+                const correspondencePath = await writeRunReport(meta.runDir, "backend-test-markdown-pytest-correspondence.md", correspondence);
+                outputs.push(`correspondence=${correspondencePath}`, correspondence);
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n\n"),
+                    stderr: "backend-test markdown-traceability requires spec.sourceBinding",
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            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);
+                const contractsDir = path.join(meta.runDir, "contracts");
+                await mkdir(contractsDir, { recursive: true });
+                const factsPath = path.join(contractsDir, "backend-test-markdown-pytest-correspondence-facts.json");
+                await writeFile(factsPath, JSON.stringify(correspondence.facts, null, 2), "utf8");
+                outputs.push(`correspondence=${correspondencePath}`, `correspondenceFacts=${factsPath}`, correspondence.markdown);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const correspondence = `# Backend Test Markdown → pytest Correspondence\n\n## Status\n\nUNAVAILABLE\n\n## Findings\n\n- Correspondence analysis crashed and is treated as an infrastructure failure: ${message}\n`;
+                const correspondencePath = await writeRunReport(meta.runDir, "backend-test-markdown-pytest-correspondence.md", correspondence);
+                outputs.push(`correspondence=${correspondencePath}`, correspondence);
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n\n"),
+                    stderr: `backend-test correspondence analysis crashed: ${message}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            // Scenario-param assessment and deterministic repair run before collection,
+            // so effective collection/fixture facts bind the final executable assets.
+            try {
+                const scenarioFactsPath = path.join(meta.runDir, "contracts", "backend-test-scenario-param-consistency-facts.json");
+                const scenarioReportPath = path.join(meta.runDir, "reports", "backend-test-scenario-param-consistency.md");
+                const scenarioFacts = await readBackendScenarioParamFacts(scenarioFactsPath);
+                const scenarioReport = await readFile(scenarioReportPath, "utf8");
+                outputs.push(`scenarioParamFinal=${scenarioReportPath}`, `scenarioParamFinalFacts=${scenarioFactsPath}`, `scenarioParamStatus=${scenarioFacts.overallStatus}`, scenarioReport);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                outputs.push("# Backend Test Scenario-Param Consistency\n\n## Status\n\nUNAVAILABLE\n\n## Findings\n\n- Pre-collection scenario-param evidence missing: " + message + "\n");
+            }
+        }
+        else if (pipeline === "markdown-manifest") {
+            const sourceBinding = meta.spec.sourceBinding;
+            if (!sourceBinding)
+                throw new Error("backend-test markdown-manifest requires spec.sourceBinding");
+            const manifest = await materializeBackendTestCaseManifestFromFacts({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+                sourceBinding: {
+                    taskId: sourceBinding.taskId,
+                    requirementPath: sourceBinding.sources.find((s) => s.kind === "requirement")?.path ??
+                        "source/requirement.md",
+                    requirementSha256: sourceBinding.sources.find((s) => s.kind === "requirement")
+                        ?.sha256 ?? "0".repeat(64),
+                    referencePaths: sourceBinding.sources
+                        .filter((s) => s.kind === "reference")
+                        .map((s) => s.path),
+                    requirementIds: sourceBinding.requirementIds,
+                },
+            });
+            const manifestPath = path.join(meta.runDir, "contracts", "backend-test-case-manifest.json");
+            const summary = manifest.coverageSummary;
+            outputs.push(`manifest=${manifestPath}`, `materializationStatus=${manifest.materializationStatus ?? "available"}`, `coverageSummary.explicitAcCount=${summary?.explicitAcCount ?? "unavailable"}`, `coverageSummary.coveredAcCount=${summary?.coveredAcCount ?? "unavailable"}`, `coverageSummary.caseCount=${summary?.caseCount ?? "unavailable"}`, `coverageSummary.generatedCount=${summary?.generatedCount ?? "unavailable"}`, `ruleCoverageSummary.ruleCount=${manifest.ruleCoverageSummary?.ruleCount ?? "unavailable"}`, `correspondenceSummary.exactCorrespondenceCount=${manifest.correspondenceSummary?.exactCorrespondenceCount ?? "unavailable"}`, `correspondenceSummary.primarySymbolCount=${manifest.correspondenceSummary?.primarySymbolCount ?? "unavailable"}`, `correspondenceSummary.testPoints=${manifest.correspondenceSummary?.mappedTestPointCount ?? "unavailable"}/${manifest.correspondenceSummary?.testPointCount ?? "unavailable"}`, `correspondenceSummary.variantTestPointCount=${manifest.correspondenceSummary?.variantTestPointCount ?? "unavailable"}`, `correspondenceSummary.assertionTestPointCount=${manifest.correspondenceSummary?.assertionTestPointCount ?? "unavailable"}`, `correspondenceSummary.crossCuttingTestPointCount=${manifest.correspondenceSummary?.crossCuttingTestPointCount ?? "unavailable"}`, `correspondenceSummary.unclassifiedTestPointCount=${manifest.correspondenceSummary?.unclassifiedTestPointCount ?? "unavailable"}`, `correspondenceSummary.duplicateBindingTestPointCount=${manifest.correspondenceSummary?.duplicateBindingTestPointCount ?? "unavailable"}`);
+        }
+        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, 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/
+            // stderr and no diagnostics file. Keep pytest exactly once.
+            const commandPlan = [
+                "shell-bootstrap",
+                "python-identity",
+                "pytest-version",
+                "pytest-run",
+            ];
+            let preSpawnOk = false;
+            try {
+                await writeBackendTestExecuteDiagnosticsPreSpawn({
+                    runDir: meta.runDir,
+                    runId: meta.runId,
+                    cwd: input.cwd,
+                    mappedScripts,
+                    commandPlan: [...commandPlan],
+                });
+                preSpawnOk = true;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    ok: false,
+                    stdout: "",
+                    stderr: [
+                        "backend-test markdown-execute-html shell failed",
+                        "failureCategory=invalid-output",
+                        `mappedScripts=${mappedScripts.join(",") || "<none>"}`,
+                        `preSpawnDiagnostics=failed`,
+                        `diagnostics=${BACKEND_TEST_EXECUTE_DIAGNOSTICS_REL}`,
+                        message,
+                    ].join("\n"),
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            // Append-only shell snippets; never overwrite the JS pre-spawn head.
+            const shellBootstrapCommand = [
+                'if [ -z "${HARNESS_DAG_RUN_DIR:-}" ]; then echo "HARNESS_DAG_RUN_DIR is empty; refusing to write diagnostics under /reports" >&2; exit 2; fi',
+                'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
+                'DIAG_FILE="${HARNESS_DAG_RUN_DIR}/reports/backend-test-execute-diagnostics.md"',
+                'echo "STEP=shell-bootstrap"',
+                'echo "- shellBootstrapAt: $(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date)" >> "${DIAG_FILE}"',
+                'echo "- shellPwd: $(pwd)" >> "${DIAG_FILE}"',
+                'echo "- shellHARNESS_DAG_RUN_DIR: ${HARNESS_DAG_RUN_DIR}" >> "${DIAG_FILE}"',
+                'echo "- shell: ${BASH:-bash} (${BASH_VERSION:-unknown})" >> "${DIAG_FILE}"',
+            ].join("; ");
+            const pythonIdentityCommand = [
+                'if [ -z "${HARNESS_DAG_RUN_DIR:-}" ]; then echo "HARNESS_DAG_RUN_DIR is empty" >&2; exit 2; fi',
+                'DIAG_FILE="${HARNESS_DAG_RUN_DIR}/reports/backend-test-execute-diagnostics.md"',
+                'echo "STEP=resolve-python"',
+                'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
+                'echo "- command_v_python: $(command -v python || true)" >> "${DIAG_FILE}"',
+                'echo "- command_v_python3: $(command -v python3 || true)" >> "${DIAG_FILE}"',
+                'echo "- PYTHON_BIN: ${PYTHON_BIN:-<empty>}" >> "${DIAG_FILE}"',
+                'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
+                'echo "STEP=python-identity"',
+                'if ! PYTHONUNBUFFERED=1 "${PYTHON_BIN}" -c "import sys; print(sys.executable); print(sys.version.splitlines()[0])" >> "${DIAG_FILE}" 2>&1; then echo "STEP=python-identity-failed" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
+            ].join("; ");
+            const pytestVersionCommand = [
+                'if [ -z "${HARNESS_DAG_RUN_DIR:-}" ]; then echo "HARNESS_DAG_RUN_DIR is empty" >&2; exit 2; fi',
+                'DIAG_FILE="${HARNESS_DAG_RUN_DIR}/reports/backend-test-execute-diagnostics.md"',
+                '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-version"',
+                'if ! PYTHONUNBUFFERED=1 "${PYTHON_BIN}" -m pytest --version >> "${DIAG_FILE}" 2>&1; then echo "STEP=pytest-version-failed" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
+            ].join("; ");
+            // Single pytest invocation; exit 0/1 + non-empty html are reportable.
+            const pytestRunCommand = [
+                'if [ -z "${HARNESS_DAG_RUN_DIR:-}" ]; then echo "HARNESS_DAG_RUN_DIR is empty" >&2; exit 2; fi',
+                'DIAG_FILE="${HARNESS_DAG_RUN_DIR}/reports/backend-test-execute-diagnostics.md"',
+                '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 <${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}"',
+                'if [ -f "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" ]; then echo "- pytestHtml: present ($(wc -c < "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" | tr -d " ") bytes)" >> "${DIAG_FILE}"; else echo "- pytestHtml: missing" >> "${DIAG_FILE}"; fi',
+                'echo "- finishedAt: $(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date)" >> "${DIAG_FILE}"',
+                'echo "STEP=pytest-finished status=${STATUS}"',
+                'if { [ "${STATUS}" -eq 0 ] || [ "${STATUS}" -eq 1 ]; } && [ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" ]; then exit 0; fi',
+                'echo "STEP=pipeline-failed status=${STATUS} html=$([ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" ] && echo present || echo missing)" >&2',
+                'exit "${STATUS}"',
+            ].join("; ");
+            const pipelineCommands = [
+                shellBootstrapCommand,
+                pythonIdentityCommand,
+                pytestVersionCommand,
+                pytestRunCommand,
+            ];
+            const results = await executePipelineCommands(input, meta, pipelineCommands);
+            if (!results.every((result) => result.ok)) {
+                const failureIndex = results.findIndex((result) => !result.ok);
+                const failure = results[failureIndex];
+                const combinedStdout = results
+                    .map((result) => result.stdout)
+                    .join("\n");
+                let diagnosticsText = "";
+                try {
+                    diagnosticsText = await readFile(path.join(meta.runDir, "reports", "backend-test-execute-diagnostics.md"), "utf8");
+                }
+                catch {
+                    diagnosticsText = "";
+                }
+                const failedStep = failureIndex >= 0 && failureIndex < commandPlan.length
+                    ? commandPlan[failureIndex]
+                    : "unknown";
+                const stderrSummary = [
+                    "backend-test markdown-execute-html shell failed",
+                    `failureCategory=${failure.failureCategory}`,
+                    `exitCode=${failure.exitCode ?? "null"}`,
+                    `durationMs=${failure.durationMs}`,
+                    `failedCommandIndex=${failureIndex + 1}`,
+                    `failedStep=${failedStep}`,
+                    `commandPlanCount=${pipelineCommands.length}`,
+                    `preSpawnDiagnostics=${preSpawnOk ? "written" : "failed"}`,
+                    `mappedScripts=${mappedScripts.join(",") || "<none>"}`,
+                    `shellStdoutEmpty=${combinedStdout.trim().length === 0}`,
+                    `shellStderrEmpty=${failure.stderr.trim().length === 0}`,
+                    failure.stdoutArtifactPath
+                        ? `commandStdoutArtifact=${failure.stdoutArtifactPath}`
+                        : undefined,
+                    failure.stderrArtifactPath
+                        ? `commandStderrArtifact=${failure.stderrArtifactPath}`
+                        : undefined,
+                    `diagnostics=${BACKEND_TEST_EXECUTE_DIAGNOSTICS_REL}`,
+                    failure.stderr.trim() || "(shell stderr empty)",
+                    diagnosticsText.trim()
+                        ? `--- diagnostics ---\n${diagnosticsText.trim()}`
+                        : "(diagnostics file missing or empty)",
+                ]
+                    .filter((line) => Boolean(line))
+                    .join("\n");
+                return {
+                    ok: false,
+                    stdout: combinedStdout,
+                    stderr: stderrSummary,
+                    failureCategory: failure.failureCategory,
+                    durationMs: Date.now() - started,
+                };
+            }
+            const reportsDir = path.join(meta.runDir, "reports");
+            const pytestHtmlContent = await readFile(path.join(reportsDir, "backend-test.html"), "utf8");
+            const pytestExitCode = Number.parseInt((await readFile(path.join(reportsDir, "backend-test-pytest-exit.txt"), "utf8")).trim(), 10);
+            if (![0, 1].includes(pytestExitCode)) {
+                throw new Error(`pytest did not complete with a reportable exit code: ${pytestExitCode}`);
+            }
+            const parsed = parsePytestHtmlReport(pytestHtmlContent);
+            // Keep native pytest-html (data-jsonblob) for audit before styled overwrite.
+            const nativeHtmlPath = await writeRunReport(meta.runDir, "backend-test-pytest-native.html", pytestHtmlContent);
+            // Bind Result v1 from the native pytest-html report BEFORE overwriting with the
+            // styled renderer (which drops the data-jsonblob island).
+            const resultArtifact = await materializeBackendTestResultFromPytestHtml({
+                runDir: meta.runDir,
+                htmlRelativePath: "reports/backend-test-pytest-native.html",
+                htmlContent: pytestHtmlContent,
+                pytestExitCode,
+            });
+            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 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,
+                cases,
+                environmentSummary: await readFile(path.join(reportsDir, "backend-test-environment.md"), "utf8"),
+                caseValidationSummary,
+                caseCoverageSummary,
+                traceabilitySummary,
+                correspondenceSummary,
+            });
+            const htmlPath = await writeRunReport(meta.runDir, "backend-test.html", htmlContent);
+            const facts = renderBackendTestFacts({
+                parsed,
+                cases,
+                pytestExitCode,
+                htmlRelativePath: "reports/backend-test.html",
+                htmlContent,
+                caseValidationSummary,
+                caseCoverageSummary,
+                traceabilitySummary,
+                correspondenceSummary,
+            });
+            const markdownPath = await writeRunReport(meta.runDir, "backend-test.md", facts);
+            const factsPath = await writeRunReport(meta.runDir, "backend-test-facts.md", facts);
+            // Structured failure analysis report (P2); emitted even when there are zero failures.
+            let scenarioParamFinalStatus = "UNAVAILABLE";
+            let scenarioParamRepairAttempt = 0;
+            const scenarioParamStatusByToken = new Map();
+            try {
+                const scenarioFacts = await readBackendScenarioParamFacts(path.join(meta.runDir, "contracts", "backend-test-scenario-param-consistency-facts.json"));
+                scenarioParamFinalStatus = scenarioFacts.overallStatus;
+                scenarioParamRepairAttempt = scenarioFacts.repairAttempt;
+                for (const entry of scenarioFacts.entries) {
+                    scenarioParamStatusByToken.set(entry.caseId, entry.status);
+                    scenarioParamStatusByToken.set(entry.tpId, entry.status);
+                }
+            }
+            catch {
+                // optional facts
+            }
+            const failureCases = parsed.cases.filter((item) => item.status === "failure" || item.status === "error");
+            const failureAnalysisMarkdown = renderBackendTestFailureAnalysis({
+                generatedAt: new Date().toISOString(),
+                htmlReportPath: "reports/backend-test.html",
+                total: parsed.tests,
+                passed: parsed.passed,
+                failed: parsed.failed,
+                errors: parsed.errors,
+                durationLabel: `${parsed.durationMs ?? failureCases.reduce((sum, item) => sum + (item.durationMs ?? 0), 0)}ms`,
+                environmentSummary: await readFile(path.join(reportsDir, "backend-test-environment.md"), "utf8").catch(() => "unavailable"),
+                scenarioParamFinalStatus,
+                repairAttempt: scenarioParamRepairAttempt,
+                failures: failureCases.map((result) => {
+                    const identityText = `${result.nodeId ?? ""} ${result.name}`;
+                    const caseToken = identityText.match(/BE[-_][A-Z0-9_-]+[-_]\d{2,3}/i)?.[0];
+                    const caseId = caseToken
+                        ? caseToken.replace(/^BE_/i, "BE-").replaceAll("_", "-").toUpperCase()
+                        : result.name;
+                    const tpToken = identityText.match(/TP-[A-Z0-9-]+/i)?.[0]?.toUpperCase();
+                    const scenarioParamStatus = (tpToken && scenarioParamStatusByToken.get(tpToken)) ||
+                        scenarioParamStatusByToken.get(caseId);
+                    const evidence = [result.message, result.details]
+                        .filter(Boolean)
+                        .join("\n");
+                    const statusMatch = /assert\s+(\d{3})\s*==\s*(\d{3})/i.exec(evidence) ||
+                        /expected[^\d]*(\d{3})[\s\S]{0,40}actual[^\d]*(\d{3})/i.exec(evidence);
+                    return {
+                        name: tpToken ?? result.name,
+                        caseId,
+                        scenario: cases.find((item) => item.id === caseId)?.scenario ??
+                            cases.find((item) => item.id === caseId)?.title ??
+                            result.name,
+                        expectedCode: statusMatch?.[2] ?? statusMatch?.[1],
+                        actualCode: statusMatch?.[1] ?? statusMatch?.[2],
+                        message: result.message || result.status,
+                        scriptPath: result.nodeId ?? result.filePath ?? result.classname,
+                        durationLabel: result.durationMs !== undefined
+                            ? `${result.durationMs}ms`
+                            : undefined,
+                        scenarioParamStatus,
+                        classification: classifyBackendTestFailureWithScenarioParam({
+                            message: result.message || "",
+                            details: result.details,
+                            scenarioParamStatus,
+                        }),
+                    };
+                }),
+            });
+            const failureAnalysisPath = await writeRunReport(meta.runDir, "backend-test-failure-analysis.md", failureAnalysisMarkdown);
+            outputs.push(`failureAnalysis=${failureAnalysisPath}`);
+            // Deterministic L-5 dashboard: machine-computed metrics (not Pi-generated).
+            // manifest is produced by an upstream finalize node; tolerate its absence
+            // so a minimal DAG without manifest still gets a degraded dashboard.
+            let manifestForL5 = {};
+            try {
+                const manifestPath = path.join(meta.runDir, "contracts", "backend-test-case-manifest.json");
+                manifestForL5 = JSON.parse(await readFile(manifestPath, "utf8"));
+            }
+            catch {
+                // manifest missing: L5 AC/automation metrics degrade to unavailable.
+            }
+            // Optional JaCoCo coverage collection (Java services). When jacocoCoverage
+            // is configured on the shell node, dump exec data over TCP from the
+            // JaCoCo tcpserver agent, convert via jacococli.jar, and parse into a
+            // code-coverage-v1 contract. Failure-safe: any error → coverage stays
+            // null and the L-5 dashboard degrades line/branch to unavailable.
+            let coverageContract = null;
+            const jacocoCfg = input.task.shell?.jacocoCoverage;
+            if (jacocoCfg) {
+                const sourceBinding = meta.spec.sourceBinding;
+                const requirementIds = sourceBinding?.requirementIds ?? [];
+                try {
+                    coverageContract = await collectJacocoCoverage({
+                        endpoint: jacocoCfg.endpoint,
+                        cliJarPath: jacocoCfg.cliJarPath,
+                        includes: jacocoCfg.includes ?? "*",
+                        connectTimeoutMs: jacocoCfg.connectTimeoutMs ?? 5000,
+                        workDir: reportsDir,
+                        sourceScope: { requirementIds, paths: [] },
+                        commitSha: null,
+                    });
+                }
+                catch {
+                    // coverage unavailable: JaCoCo endpoint unreachable or parse failed.
+                }
+                if (coverageContract) {
+                    const contractsDir = path.join(meta.runDir, "contracts");
+                    await mkdir(contractsDir, { recursive: true });
+                    await writeFile(path.join(contractsDir, "code-coverage-v1.json"), JSON.stringify(coverageContract, null, 2), "utf8");
+                }
+            }
+            const l5Metrics = computeL5ReportMetrics({
+                result: {
+                    passed: parsed.passed,
+                    failed: parsed.failed,
+                    error: parsed.errors,
+                    skipped: parsed.skipped,
+                },
+                manifest: manifestForL5,
+                coverage: coverageContract,
+                criticalRiskCount: parsed.failed + parsed.errors > 0 ? 1 : 0,
+            });
+            const failureSummaries = parsed.cases
+                .filter((c) => c.status !== "passed")
+                .map((c) => {
+                const id = c.name.match(/BE-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}/)?.[0] ?? c.name;
+                return {
+                    caseId: id,
+                    title: c.name,
+                    message: c.message ?? c.status,
+                    script: `${c.classname.split("::")[0] ?? c.classname}`,
+                };
+            });
+            const l5Html = renderBackendTestL5Dashboard({
+                title: meta.spec.title,
+                objective: meta.spec.objective,
+                parsed,
+                metrics: l5Metrics,
+                caseValidationSummary,
+                caseCoverageSummary,
+                traceabilitySummary,
+                correspondenceSummary,
+                failures: failureSummaries.length > 0 ? failureSummaries : undefined,
+            });
+            const l5Path = await writeRunReport(meta.runDir, "backend-test-l5-dashboard.html", l5Html);
+            const sanitizedOutputs = results.map((result) => redactBackendTestOutput(result.stdout));
+            outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `nativeHtml=${nativeHtmlPath}`, `markdown=${markdownPath}`, `facts=${factsPath}`, `l5-dashboard=${l5Path}`, `result=${resultArtifact.path}`, facts);
+        }
+        else if (pipeline === "contracts") {
+            const wrapperPath = path.join(meta.runDir, "analyze-and-discover-backend-test-pi.json");
+            const wrapper = JSON.parse(await readFile(wrapperPath, "utf8"));
+            const raw = wrapper.assistantText?.trim() || wrapper.stdout?.trim() || "";
+            const envelope = extractBackendTestContractEnvelope(raw);
+            await writeFile(path.join(meta.runDir, "backend-test-analysis-envelope.json"), JSON.stringify({ assistantText: JSON.stringify(envelope.analysis) }));
+            await writeFile(path.join(meta.runDir, "backend-test-execution-envelope.json"), JSON.stringify({ assistantText: JSON.stringify(envelope.execution) }));
+            const analysis = await materializeBackendTestAnalysisContract({
+                runDir: meta.runDir,
+                fromNodeId: "backend-test-analysis-envelope",
+                artifactName: "backend-test-analysis.json",
+                outputDir: "contracts",
+                sourceBinding: meta.spec.sourceBinding,
+            });
+            const execution = await materializeBackendTestExecutionContract({
+                runDir: meta.runDir,
+                fromNodeId: "backend-test-execution-envelope",
+                artifactName: "backend-test-execution.json",
+                outputDir: "contracts",
+                allowedTestRoot: backendLayout.testRoot,
+            });
+            outputs.push(`analysis=${analysis.path}`, `execution=${execution.path}`);
+        }
+        else if (pipeline === "semantic-initial") {
+            // Same pipeline id for node 09 (materialize+trace) and node 10 (pass-only authorize).
+            // Branch only on task.id so request-revision remains materializable at 09 and fail-closed at 10.
+            if (input.task.id === "backend-test-semantic-gate-shell") {
+                const artifactPath = path.join(meta.runDir, "contracts", "backend-test-semantic-review.json");
+                let raw;
+                try {
+                    raw = await readFile(artifactPath, "utf8");
+                }
+                catch {
+                    return {
+                        ok: false,
+                        stdout: "",
+                        stderr: "backend-test semantic authorize: missing canonical artifact contracts/backend-test-semantic-review.json",
+                        failureCategory: "invalid-output",
+                        durationMs: Date.now() - started,
+                    };
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    return {
+                        ok: false,
+                        stdout: "",
+                        stderr: "backend-test semantic authorize: malformed canonical artifact contracts/backend-test-semantic-review.json",
+                        failureCategory: "invalid-output",
+                        durationMs: Date.now() - started,
+                    };
+                }
+                if (!parsed ||
+                    typeof parsed !== "object" ||
+                    Array.isArray(parsed) ||
+                    !["verdict", "findings", "summary"].every((key) => Object.hasOwn(parsed, key))) {
+                    return {
+                        ok: false,
+                        stdout: "",
+                        stderr: "backend-test semantic authorize: malformed canonical artifact (missing required canonical fields)",
+                        failureCategory: "invalid-output",
+                        durationMs: Date.now() - started,
+                    };
+                }
+                const validated = backendTestSemanticReviewSchema.safeParse(parsed);
+                if (!validated.success) {
+                    const detail = validated.error.issues
+                        .map((issue) => `${issue.path.join(".") || "artifact"}: ${issue.message}`)
+                        .join("; ");
+                    return {
+                        ok: false,
+                        stdout: "",
+                        stderr: `backend-test semantic authorize: malformed canonical artifact (strict schema validation failed: ${detail})`,
+                        failureCategory: "invalid-output",
+                        durationMs: Date.now() - started,
+                    };
+                }
+                const review = validated.data;
+                if (review.verdict === "pass") {
+                    return {
+                        ok: true,
+                        stdout: JSON.stringify(review),
+                        stderr: "",
+                        failureCategory: "success",
+                        durationMs: Date.now() - started,
+                    };
+                }
+                return {
+                    ok: false,
+                    stdout: JSON.stringify(review),
+                    stderr: "backend-test semantic authorize blocked: verdict=request-revision",
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            const review = await materializeBackendTestSemanticReview({
+                runDir: meta.runDir,
+                fromNodeId: "review-generated-backend-pytest-pi",
+                artifactName: "backend-test-semantic-review.json",
+                outputDir: "contracts",
+            });
+            const trace = await runBackendTestTraceabilityGate({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+            });
+            outputs.push(`semantic=${review.path}`, formatTraceabilityGateStdout(trace));
+            const parsed = JSON.parse(await readFile(review.path, "utf8"));
+            return {
+                ok: true,
+                stdout: JSON.stringify(parsed),
+                stderr: "",
+                failureCategory: "success",
+                durationMs: Date.now() - started,
+            };
+        }
+        else if (pipeline === "execute-parse-initial") {
+            const results = await executePipelineCommands(input, meta);
+            if (!results.every((result) => result.ok)) {
+                const failure = results.find((result) => !result.ok);
+                return {
+                    ok: false,
+                    stdout: results.map((result) => result.stdout).join("\n"),
+                    stderr: failure.stderr,
+                    failureCategory: failure.failureCategory,
+                    durationMs: Date.now() - started,
+                };
+            }
+            const artifact = await materializeBackendTestResultFromRunDir({
+                runDir: meta.runDir,
+                fromNodeId: input.task.id,
+                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}`);
+        }
+        else if (pipeline === "classification-result-context") {
+            const classification = await materializeBackendTestClassification({
+                runDir: meta.runDir,
+                fromNodeId: "classify-backend-test-result-pi",
+                artifactName: "backend-test-classification.json",
+                outputDir: "contracts",
+            });
+            const selected = await executePipelineCommands(input, meta, [
+                buildBackendTestCanonicalResultFromInitialShellSnippet(),
+            ]);
+            if (!selected.every((result) => result.ok))
+                throw new Error(selected.find((result) => !result.ok)?.stderr ||
+                    "canonical result materialization failed");
+            const readNodeOutput = async (nodeId) => {
+                const record = JSON.parse(await readFile(path.join(meta.runDir, `${nodeId}.json`), "utf8"));
+                const text = record.assistantText?.trim() || record.stdout?.trim() || "";
+                if (!text)
+                    throw new Error(`missing auditable node output: ${nodeId}`);
+                return text;
+            };
+            const caseReview = await readNodeOutput("review-backend-cases-pi");
+            const reviewVerdicts = caseReview
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter((line) => line.startsWith("VERDICT:"));
+            if (reviewVerdicts.length !== 1 ||
+                !["VERDICT: pass", "VERDICT: request-revision"].includes(reviewVerdicts[0])) {
+                throw new Error("invalid advisory case review evidence: expected exactly one auditable VERDICT line");
+            }
+            const traceability = await readNodeOutput("backend-test-traceability-gate-shell");
+            if (!traceability.includes("Traceability gate: pass") ||
+                !/Matched symbols:\s*\d+/.test(traceability)) {
+                throw new Error("invalid traceability evidence: deterministic pass summary is missing");
+            }
+            const contracts = path.join(meta.runDir, "contracts");
+            const context = {
+                schemaVersion: 1,
+                result: JSON.parse(await readFile(path.join(contracts, "backend-test-result.json"), "utf8")),
+                manifest: JSON.parse(await readFile(path.join(contracts, "backend-test-case-manifest.json"), "utf8")),
+                classification: JSON.parse(await readFile(path.join(contracts, "backend-test-classification.json"), "utf8")),
+                caseReview: {
+                    verdict: reviewVerdicts[0].slice("VERDICT: ".length),
+                    evidence: caseReview,
+                },
+                traceability: { status: "pass", evidence: traceability },
+            };
+            outputs.push(`classification=${classification.path}`, ...selected.map((result) => result.stdout), JSON.stringify(context, null, 2));
+        }
+        else {
+            throw new Error(`unsupported backend-test pipeline: ${pipeline}`);
+        }
+        return {
+            ok: true,
+            stdout: outputs.filter(Boolean).join("\n"),
+            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 executeBackendTestPipelineWithWriteGuard(input, meta) {
+    let beforeStatus;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        // Non-git cwd: keep the same documented limitation as normal shell nodes.
+        beforeStatus = undefined;
+    }
+    const result = await executeBackendTestPipeline(input, meta);
+    if (beforeStatus === undefined)
+        return result;
+    try {
+        const guard = await runShellWriteGuard({
+            rootCwd: input.cwd,
+            task: input.task,
+            beforeStatus,
+        });
+        if (guard.ok)
+            return result;
+        const detail = `write guard failed: ${guard.violations.join(", ")}`;
+        return {
+            ...result,
+            ok: false,
+            stderr: [result.stderr, detail].filter(Boolean).join("\n\n"),
+            failureCategory: "write-guard",
+        };
+    }
+    catch (error) {
+        const detail = `write guard failed: git status unavailable: ${error instanceof Error ? error.message : String(error)}`;
+        return {
+            ...result,
+            ok: false,
+            stderr: [result.stderr, detail].filter(Boolean).join("\n\n"),
+            failureCategory: "write-guard",
+        };
+    }
+}
+async function executePipelineCommands(input, meta, overrideCommands) {
+    const shell = input.task.shell;
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    const commands = overrideCommands ?? shell.commands;
+    const results = [];
+    for (const command of commands) {
+        const commandNumber = results.length + 1;
+        const result = await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+            envAllowlist: shell.envAllowlist,
+            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`),
+            },
+        });
+        results.push(result);
+        if (!result.ok)
+            break;
+    }
+    return results;
+}
+async function executeFrontendVerificationBundle(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const bundle = shell.frontendVerificationBundle;
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    const results = [];
+    let beforeStatus;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        beforeStatus = undefined;
+    }
+    const lintResults = [];
+    for (const command of bundle.lintCommands ?? []) {
+        const commandNumber = results.length + 1;
+        const result = await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+            envAllowlist: shell.envAllowlist,
+            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`),
+            },
+        });
+        lintResults.push(result);
+        results.push(result);
+    }
+    let lintAssessment;
+    if ((bundle.lintCommands?.length ?? 0) > 0 &&
+        bundle.lintBaselineNodeId &&
+        (bundle.writerNodeIds?.length ?? 0) > 0) {
+        lintAssessment = await materializeFrontendLintAssessment({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            commands: bundle.lintCommands,
+            results: lintResults,
+            baselineNodeId: bundle.lintBaselineNodeId,
+            writerNodeIds: bundle.writerNodeIds,
+        });
+    }
+    const lintBlocked = lintAssessment?.status === "failed" ||
+        lintAssessment?.status === "unavailable";
+    const groups = [
+        {
+            name: "mock",
+            commands: bundle.mockCommands,
+            labels: bundle.mockEvidence?.commandLabels ?? [],
+        },
+        {
+            name: "static",
+            commands: bundle.staticCommands,
+            labels: bundle.staticEvidence.commandLabels,
+        },
+        {
+            name: "behavior",
+            commands: bundle.behaviorCommands,
+            labels: bundle.behaviorEvidence.commandLabels,
+        },
+    ];
+    const successfulLabels = new Map();
+    for (const group of lintBlocked ? [] : groups) {
+        for (const [index, command] of group.commands.entries()) {
+            const commandNumber = results.length + 1;
+            const result = await executeShellCommand({
+                command,
+                cwd,
+                timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+                envAllowlist: shell.envAllowlist,
+                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`),
+                },
+            });
+            results.push(result);
+            if (result.ok && group.labels[index]) {
+                const labels = successfulLabels.get(group.name) ?? [];
+                labels.push(group.labels[index]);
+                successfulLabels.set(group.name, labels);
+            }
+            if (!result.ok)
+                break;
+        }
+    }
+    if (beforeStatus !== undefined) {
+        const guard = await runShellWriteGuard({
+            rootCwd: input.cwd,
+            task: input.task,
+            beforeStatus,
+        });
+        if (!guard.ok) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `write guard failed: ${guard.violations.join(", ")}`,
+                failureCategory: "write-guard",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    await writeDagNodeTextArtifact(meta.runDir, input.task.id, "result.summary.md", buildShellResultSummaryMarkdown({
+        nodeId: input.task.id,
+        runId: meta.runId,
+        rootCwd: input.cwd,
+        results,
+    }));
+    const commandResults = results.map((result) => ({
+        ok: result.ok,
+        exitCode: result.exitCode,
+        failureCategory: result.failureCategory,
+        command: result.command,
+    }));
+    const firstFailure = lintBlocked
+        ? lintResults.find((result) => !result.ok)
+        : results
+            .filter((result) => !lintResults.includes(result))
+            .find((result) => !result.ok);
+    const lintSyntheticFailure = lintBlocked && !firstFailure
+        ? {
+            failureCategory: "invalid-output",
+            stderr: lintAssessment?.blockingReasons.join("; ") ??
+                "frontend lint assessment failed",
+        }
+        : undefined;
+    let traceError;
+    try {
+        await runFrontendVerificationTraceGate({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            evidence: {
+                mock: {
+                    nodeId: input.task.id,
+                    commandLabels: successfulLabels.get("mock") ?? [],
+                    commandTexts: bundle.mockCommands.slice(0, successfulLabels.get("mock")?.length ?? 0),
+                },
+                static: {
+                    nodeId: input.task.id,
+                    commandLabels: successfulLabels.get("static") ?? [],
+                },
+                behavior: {
+                    nodeId: input.task.id,
+                    commandLabels: successfulLabels.get("behavior") ?? [],
+                },
+            },
+        });
+    }
+    catch (error) {
+        traceError = error instanceof Error ? error : new Error(String(error));
+    }
+    if (bundle.mode === "repair") {
+        if (firstFailure || lintSyntheticFailure || traceError) {
+            return {
+                ok: false,
+                stdout: summarizeCommandResults(results).stdout,
+                stderr: firstFailure?.stderr ||
+                    lintSyntheticFailure?.stderr ||
+                    traceError?.message ||
+                    "frontend reverify failed",
+                failureCategory: firstFailure?.failureCategory ??
+                    lintSyntheticFailure?.failureCategory ??
+                    "invalid-output",
+                durationMs: Date.now() - started,
+                ...{ commandResults },
+            };
+        }
+        return {
+            ok: true,
+            stdout: lintAssessment?.status === "baseline-debt"
+                ? "Frontend reverify bundle: pass with lint baseline-debt"
+                : "Frontend reverify bundle: pass",
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+    const failureFacts = [];
+    if (firstFailure || lintSyntheticFailure) {
+        const failureStdout = firstFailure
+            ? [firstFailure.command, firstFailure.stdout].filter(Boolean).join("\n")
+            : "";
+        failureFacts.push({
+            nodeId: input.task.id,
+            record: {
+                status: "FINISHED",
+                failureCategory: firstFailure?.failureCategory ??
+                    lintSyntheticFailure?.failureCategory,
+                // Keep classification scoped to the failed command. Aggregate
+                // successful output may contain unrelated writeSet-like JSON.
+                stdout: failureStdout,
+                stderr: firstFailure?.stderr ?? lintSyntheticFailure?.stderr,
+                commandResults,
+            },
+        });
+    }
+    if (traceError) {
+        failureFacts.push({
+            nodeId: "frontend-verification-trace-shell",
+            record: {
+                status: "FINISHED",
+                failureCategory: "invalid-output",
+                stderr: traceError.message,
+            },
+        });
+    }
+    try {
+        const assessment = await runFrontendFailureAssessGate({
+            runDir: meta.runDir,
+            failureFacts,
+        });
+        await runFrontendRepairContractGate({ runDir: meta.runDir });
+        return {
+            ok: true,
+            stdout: formatFrontendFailureAssessStdout(assessment),
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+}
+async function executeFrontendTestCaseChecklist(input, meta) {
+    const started = Date.now();
+    try {
+        const declaredAcIds = (meta.spec.sourceBinding?.requirementIds ?? []).filter((id) => /^AC(?:-[A-Z0-9]+)+$/i.test(id));
+        const result = await validateFrontendCaseChecklist({
+            workspaceRoot: input.cwd,
+            declaredAcIds,
+        });
+        if (result.issues.length) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend-test checklist blocked: ${JSON.stringify(result.issues)}`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        return {
+            ok: true,
+            stdout: `frontend-test checklist ok cases=${result.caseCount} source=${path.basename(result.manifestPath)}`,
+            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 executeFrontendTestL5Report(input, meta) {
+    const started = Date.now();
+    try {
+        const output = await renderFrontendTestL5Report({
+            workspaceRoot: input.cwd,
+            runDir: meta.runDir,
+        });
+        return {
+            ok: true,
+            stdout: `Frontend L-5 report: ${output.htmlPath}\nMarkdown: ${output.markdownPath}\nStatus: ${output.metrics.status}`,
+            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 executeFrontendTestHtmlReport(input, meta) {
+    const started = Date.now();
+    try {
+        const output = await renderFrontendTestHtmlReport({
+            workspaceRoot: input.cwd,
+            runDir: meta.runDir,
+        });
+        return {
+            ok: true,
+            stdout: `Frontend test report: ${output.htmlPath}\nMarkdown: ${output.markdownPath}\nOutcome: ${output.outcome}\nCases: ${output.caseCount}`,
+            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 executeFrontendTestEvidenceValidation(input) {
+    const started = Date.now();
+    try {
+        const result = await validateFrontendCaseEvidence({
+            workspaceRoot: input.cwd,
+        });
+        const output = `frontend case evidence validation cases=${result.cases} findings=${result.issues.length}${result.issues.length ? ` issues=${JSON.stringify(result.issues)}` : ""}`;
+        if (result.hardFail) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend-test evidence hard-fail: ${JSON.stringify(result.issues)}`,
+                failureCategory: "nonzero-exit",
+                durationMs: Date.now() - started,
+            };
+        }
+        return {
+            ok: true,
+            stdout: output,
+            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 executeFrontendTestCaseManifest(input, meta) {
+    const started = Date.now();
+    try {
+        const gate = input.task.shell?.frontendTestCaseManifest ?? {};
+        const declaredAcIds = gate.declaredAcIds ??
+            (meta.spec.sourceBinding?.requirementIds ?? []).filter((id) => /^AC(?:-[A-Z0-9]+)+$/i.test(id));
+        const checklist = await validateFrontendCaseChecklist({
+            workspaceRoot: input.cwd,
+            declaredAcIds,
+        });
+        if (checklist.issues.length) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `frontend-test checklist blocked: ${JSON.stringify(checklist.issues)}`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+        const materialized = await materializeFrontendTestCaseManifest({
+            workspaceRoot: input.cwd,
+            maxCases: gate.maxCases,
+            declaredAcIds,
+        });
+        return {
+            ok: true,
+            stdout: `${JSON.stringify({ cases: materialized.cases })}
+`,
+            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,
+        };
+    }
+}
+/** Path-escape / cross-case evidence errors must hard-fail finalize (same class as validate.hardFail). */
+function isFrontendTestEvidencePathHardError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /unsafe evidence|escapes (?:evidence root|its allowed root)|evidence realpath|cross-case/i.test(message);
+}
+/**
+ * Lean finalize: evidence validate + result materialize in one shell.
+ * - Case-level missing/malformed evidence is advisory (issues / advisoryFindings);
+ *   the node still succeeds so reports can render incomplete/failed outcomes.
+ * - Path escape / unsafe evidence roots hard-fail the node.
+ * - Controller/contract errors (missing sourceBinding, empty manifest) still fail closed.
+ */
+async function executeFrontendTestResultFinalize(input, meta) {
+    const started = Date.now();
+    let advisoryStdout = "";
+    try {
+        const evidence = await validateFrontendCaseEvidence({
+            workspaceRoot: input.cwd,
+        });
+        advisoryStdout = `frontend case evidence validation cases=${evidence.cases} findings=${evidence.issues.length}${evidence.issues.length ? ` issues=${JSON.stringify(evidence.issues)}` : ""}`;
+        // Advisory findings must not block materialize; only hardFail (path escape) does.
+        if (evidence.hardFail) {
+            return {
+                ok: false,
+                stdout: advisoryStdout,
+                stderr: `frontend-test evidence hard-fail: ${JSON.stringify(evidence.issues)}`,
+                failureCategory: "nonzero-exit",
+                durationMs: Date.now() - started,
+            };
+        }
+        const artifact = await materializeFrontendTestResult({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            artifactName: "frontend-test-result.json",
+            outputDir: "contracts",
+            sourceBinding: meta.spec.sourceBinding,
+        });
+        return {
+            ok: true,
+            stdout: `${advisoryStdout}\nStructured artifact: ${artifact.path}\nSchema: ${artifact.schemaId}\nSHA-256: ${artifact.sha256}`,
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (isFrontendTestEvidencePathHardError(error)) {
+            return {
+                ok: false,
+                stdout: advisoryStdout,
+                stderr: `frontend-test evidence hard-fail: ${detail}`,
+                failureCategory: "nonzero-exit",
+                durationMs: Date.now() - started,
+            };
+        }
+        return {
+            ok: false,
+            stdout: advisoryStdout,
+            stderr: detail,
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+        };
+    }
+}
+async function executeFrontendTestReports(input, meta) {
+    const started = Date.now();
+    try {
+        const writeL5 = input.task.shell?.frontendTestReports?.l5 !== false;
+        const lines = [];
+        if (writeL5) {
+            const l5 = await renderFrontendTestL5Report({
+                workspaceRoot: input.cwd,
+                runDir: meta.runDir,
+            });
+            lines.push(`Frontend L-5 report: ${l5.htmlPath}\nMarkdown: ${l5.markdownPath}\nStatus: ${l5.metrics.status}`);
+        }
+        const report = await renderFrontendTestHtmlReport({
+            workspaceRoot: input.cwd,
+            runDir: meta.runDir,
+        });
+        lines.push(`Frontend test report: ${report.htmlPath}\nMarkdown: ${report.markdownPath}\nOutcome: ${report.outcome}\nCases: ${report.caseCount}`);
+        return {
+            ok: true,
+            stdout: lines.join("\n"),
+            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 executeFrontendLintBaseline(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const baseline = shell.frontendLintBaseline;
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    let beforeStatus;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        beforeStatus = undefined;
+    }
+    const results = [];
+    for (const command of baseline.lintCommands) {
+        const commandNumber = results.length + 1;
+        results.push(await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+            envAllowlist: shell.envAllowlist,
+            dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
+            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`),
+            },
+        }));
+    }
+    let afterStatus;
+    try {
+        afterStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        afterStatus = undefined;
+    }
+    try {
+        const materialized = await materializeFrontendLintBaseline({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            commands: baseline.lintCommands,
+            results,
+            worktreeChanged: beforeStatus === undefined ||
+                afterStatus === undefined ||
+                beforeStatus !== afterStatus,
+        });
+        return {
+            ok: true,
+            stdout: `Frontend lint baseline: ${materialized.artifact.status}\nArtifact: ${materialized.ref.path}\nDiagnostics: ${materialized.artifact.diagnostics.length}`,
+            stderr: materialized.artifact.reason ?? "",
+            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,
+        };
+    }
+}
+export async function executeDagShellNode(input, meta) {
+    const shell = input.task.shell;
+    if (shell?.finalWriteSetApprovalGate) {
+        const started = Date.now();
+        try {
+            const state = await readRunState(meta.runDir);
+            const writer = meta.spec.tasks.find((task) => task.id === shell.finalWriteSetApprovalGate.writerNodeId);
+            if (!writer)
+                throw new Error("final write-set approval gate writer is missing");
+            const authorization = parseAndValidateFinalWriteSetApproval({
+                task: writer,
+                spec: meta.spec,
+                state,
+            });
+            if (!authorization.ok)
+                throw new Error(authorization.reason);
+            return {
+                ok: true,
+                stdout: JSON.stringify({
+                    status: "approved",
+                    writerNodeId: writer.id,
+                    approvalDigest: authorization.approvalDigest,
+                    effectiveWriteSet: authorization.effectiveWriteSet,
+                }),
+                stderr: "",
+                failureCategory: "success",
+                durationMs: Date.now() - started,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `final-write-set-approval-invalid: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (shell?.frontendBrowserToolPreflight) {
+        const started = Date.now();
+        try {
+            if (resolvePiBackend() === "cli-only") {
+                throw new Error("browser-command-capability-unavailable: CODE_AGENT_PI_BACKEND=cli-only rejects SDK-only playwright_cli");
+            }
+            const sdkCapability = await checkPiSdkCustomToolCapability(input.cwd);
+            if (!sdkCapability.ok) {
+                throw new Error(`browser-command-capability-unavailable: ${sdkCapability.detail}`);
+            }
+            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") {
+                throw new Error("browser-command-capability-unavailable: structured playwright_cli tool registration failed");
+            }
+            const launcher = resolvePlaywrightCliLauncher(input.cwd);
+            const result = await defaultPlaywrightCliCommandRunner({
+                executable: launcher.executable,
+                argv: [...launcher.argvPrefix, "--help"],
+                cwd: input.cwd,
+                timeoutMs: 30_000,
+                env: { ...process.env, CI: process.env.CI ?? "1" },
+            });
+            const help = `${result.stdout}\n${result.stderr}`;
+            if (result.exitCode !== 0 ||
+                result.timedOut ||
+                !["open", "close", "find", "snapshot", "click"].every((command) => new RegExp(`\\b${command}\\b`, "i").test(help))) {
+                throw new Error("playwright-cli-contract-incompatible");
+            }
+            const capability = {
+                schemaVersion: 1,
+                status: "ready",
+                tool: "playwright-cli",
+                launcher: "verified-js-entry",
+                sdkCustomToolCapability: true,
+                structuredToolName: toolProbe.name,
+                targetUrlAuthority: "retrieve-context-and-environment-probe",
+            };
+            await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "frontend-browser-capability.json", capability);
+            return {
+                ok: true,
+                stdout: JSON.stringify(capability),
+                stderr: "",
+                failureCategory: "success",
+                durationMs: Date.now() - started,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `playwright-cli-unavailable: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (shell?.frontendPrewriteGate) {
+        const started = Date.now();
+        try {
+            const result = await runFrontendPrewriteGate({
+                runDir: meta.runDir,
+                config: shell.frontendPrewriteGate,
+                sourceBinding: meta.spec.sourceBinding,
+                workspaceRoot: input.cwd,
+                repoRoot: input.cwd,
+            });
+            return {
+                ok: true,
+                stdout: formatFrontendPrewriteGateStdout(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,
+            };
+        }
+    }
+    if (shell?.frontendLintBaseline) {
+        return executeFrontendLintBaseline(input, meta);
+    }
+    if (shell?.frontendVerificationBundle) {
+        return executeFrontendVerificationBundle(input, meta);
+    }
+    if (shell?.frontendReviewContext) {
+        const started = Date.now();
+        try {
+            const result = await runFrontendReviewContextGate({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+                requireBaseline: shell.frontendReviewContext.requireBaseline,
+            });
+            return {
+                ok: true,
+                stdout: formatFrontendReviewContextStdout(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,
+            };
+        }
+    }
+    if (shell?.frontendTestCaseChecklist) {
+        return executeFrontendTestCaseChecklist(input, meta);
+    }
+    if (shell?.frontendTestCaseManifest) {
+        return executeFrontendTestCaseManifest(input, meta);
+    }
+    if (shell?.frontendTestEvidenceValidation) {
+        return executeFrontendTestEvidenceValidation(input);
+    }
+    if (shell?.frontendTestResultFinalize) {
+        return executeFrontendTestResultFinalize(input, meta);
+    }
+    if (shell?.frontendTestL5Report) {
+        return executeFrontendTestL5Report(input, meta);
+    }
+    if (shell?.frontendTestHtmlReport) {
+        return executeFrontendTestHtmlReport(input, meta);
+    }
+    if (shell?.frontendTestReports) {
+        return executeFrontendTestReports(input, meta);
+    }
+    if (shell?.backendTestPipeline) {
+        return executeBackendTestPipelineWithWriteGuard(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
+                ? await resolveJsonArtifactSourceNodeId({
+                    runDir: meta.runDir,
+                    fromNodeId: gate.fromNodeId,
+                    fallbackFromNodeIds: gate.fallbackFromNodeIds,
+                })
+                : gate.fromNodeId;
+            let artifact;
+            switch (gate.schemaId) {
+                case "backend-test-analysis-v1":
+                case "backend-test-analysis-v2":
+                    artifact = await materializeBackendTestAnalysisContract({
+                        runDir: meta.runDir,
+                        fromNodeId: sourceNodeId,
+                        artifactName: gate.artifactName,
+                        outputDir: gate.outputDir,
+                        sourceBinding: meta.spec.sourceBinding,
+                    });
+                    break;
+                case "backend-test-execution-v1":
+                    artifact = await materializeBackendTestExecutionContract({
+                        runDir: meta.runDir,
+                        fromNodeId: sourceNodeId,
+                        artifactName: gate.artifactName,
+                        outputDir: gate.outputDir,
+                        allowedTestRoot: backendLayout.testRoot,
+                    });
+                    break;
+                case "backend-test-result-v1":
+                    artifact = await materializeBackendTestResultFromRunDir({
+                        runDir: meta.runDir,
+                        fromNodeId: sourceNodeId,
+                        artifactName: gate.artifactName,
+                        outputDir: gate.outputDir,
+                        junitRelativePath: gate.junitRelativePath,
+                        testRoot: backendLayout.testRoot,
+                    });
+                    break;
+                case "backend-test-classification-v1":
+                    artifact = await materializeBackendTestClassification({
+                        runDir: meta.runDir,
+                        fromNodeId: sourceNodeId,
+                        artifactName: gate.artifactName,
+                        outputDir: gate.outputDir,
+                    });
+                    break;
+                case "backend-test-semantic-review-v1":
+                    artifact = await materializeBackendTestSemanticReview({
+                        runDir: meta.runDir,
+                        fromNodeId: sourceNodeId,
+                        artifactName: gate.artifactName,
+                        outputDir: gate.outputDir,
+                    });
+                    break;
+                case "backend-test-case-manifest-v1":
+                    artifact = await materializeBackendTestCaseManifest({
+                        runDir: meta.runDir,
+                        fromNodeId: sourceNodeId,
+                        artifactName: gate.artifactName,
+                        outputDir: gate.outputDir,
+                        sourceBinding: meta.spec.sourceBinding,
+                    });
+                    break;
+                case "frontend-implementation-contract-v1":
+                    artifact = await materializeFrontendImplementationContract({
+                        runDir: meta.runDir,
+                        fromNodeId: sourceNodeId,
+                        artifactName: gate.artifactName,
+                        outputDir: gate.outputDir,
+                        sourceBinding: meta.spec.sourceBinding,
+                    });
+                    break;
+                case "frontend-test-result-v1":
+                    artifact = await materializeFrontendTestResult({
+                        runDir: meta.runDir,
+                        workspaceRoot: input.cwd,
+                        artifactName: gate.artifactName,
+                        outputDir: gate.outputDir,
+                        sourceBinding: meta.spec.sourceBinding,
+                    });
+                    break;
+                default:
+                    throw new Error(`unsupported jsonArtifactGate.schemaId: ${String(gate.schemaId)}`);
+            }
+            return {
+                ok: true,
+                stdout: `Structured artifact: ${artifact.path}\nSchema: ${artifact.schemaId}\nSHA-256: ${artifact.sha256}`,
+                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,
+            };
+        }
+    }
+    if (shell?.commands?.length === 1 &&
+        shell.commands[0] === "backend-test-traceability-gate") {
+        const started = Date.now();
+        try {
+            const result = await runBackendTestTraceabilityGate({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+            });
+            return {
+                ok: true,
+                stdout: formatTraceabilityGateStdout(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,
+            };
+        }
+    }
+    if (shell?.commands?.length === 1 &&
+        shell.commands[0] === "frontend-verification-trace-gate") {
+        const started = Date.now();
+        try {
+            const result = await runFrontendVerificationTraceGate({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+            });
+            return {
+                ok: true,
+                stdout: formatFrontendVerificationTraceStdout(result),
+                stderr: "",
+                failureCategory: "success",
+                durationMs: Date.now() - started,
+            };
+        }
+        catch (error) {
+            const stderr = error instanceof Error ? error.message : String(error);
+            const recordNonZero = shell.nonZeroExitPolicy === "record";
+            return {
+                ok: recordNonZero,
+                stdout: recordNonZero
+                    ? "nonZeroExitPolicy=record failureCategory=invalid-output\n"
+                    : "",
+                stderr,
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (shell?.commands?.length === 1 &&
+        shell.commands[0] === "frontend-worktree-diff-gate") {
+        const started = Date.now();
+        try {
+            const result = await runFrontendWorktreeDiffGate({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+            });
+            return {
+                ok: true,
+                stdout: formatFrontendWorktreeDiffStdout(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,
+            };
+        }
+    }
+    if (shell?.commands?.length === 1 &&
+        shell.commands[0] === "frontend-failure-assess-gate") {
+        const started = Date.now();
+        try {
+            const result = await runFrontendFailureAssessGate({
+                runDir: meta.runDir,
+            });
+            return {
+                ok: true,
+                stdout: formatFrontendFailureAssessStdout(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,
+            };
+        }
+    }
+    if (shell?.commands?.length === 1 &&
+        shell.commands[0] === "frontend-repair-contract-gate") {
+        const started = Date.now();
+        try {
+            const result = await runFrontendRepairContractGate({
+                runDir: meta.runDir,
+            });
+            return {
+                ok: true,
+                stdout: formatFrontendRepairContractStdout(result.assessment),
+                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,
+            };
+        }
+    }
+    if (shell?.projectGovernanceGate) {
+        const started = Date.now();
+        try {
+            const state = await readRunState(meta.runDir);
+            if (!state.projectGovernanceContextRef) {
+                throw new Error("project governance gate requires projectGovernanceContextRef in run state");
+            }
+            const context = await readProjectGovernanceContext(meta.runDir, state.projectGovernanceContextRef, { expectedRunId: meta.runId });
+            if (!context.applicable) {
+                return {
+                    ok: true,
+                    stdout: "Project governance gate: not applicable for this writer changeset.",
+                    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,
+            };
+        }
+    }
+    const commands = shell ? resolveShellCommands(shell) : [];
+    if (!shell || commands.length === 0) {
+        throw new Error(`shell task ${input.task.id} requires shell.preset, shell.verdictGate, and/or non-empty shell.commands`);
+    }
+    const started = Date.now();
+    if (shell.mavenVerificationPlan) {
+        try {
+            assertMavenPlanFresh(input.cwd, shell.mavenVerificationPlan, { shellCommands: commands });
+        }
+        catch (error) {
+            const message = error instanceof MavenPlanStaleError
+                ? error.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            const staleMessage = message.includes("verification-plan-stale")
+                ? message
+                : `verification-plan-stale: ${message}`;
+            const staleResults = commands.map((command) => ({
+                command,
+                cwd: input.cwd,
+                durationMs: 0,
+                wallDurationMs: 0,
+                startedAt: new Date().toISOString(),
+                finishedAt: new Date().toISOString(),
+                exitCode: null,
+                failureCategory: "verification-plan-stale",
+                ok: false,
+                stderr: staleMessage,
+                stderrBytes: Buffer.byteLength(staleMessage),
+                stderrTruncated: false,
+                stdout: "",
+                stdoutBytes: 0,
+                stdoutTruncated: false,
+                timedOut: false,
+            }));
+            await writeDagNodeTextArtifact(meta.runDir, input.task.id, "result.summary.md", buildShellResultSummaryMarkdown({
+                nodeId: input.task.id,
+                runId: meta.runId,
+                rootCwd: input.cwd,
+                results: staleResults,
+            }));
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `${staleMessage}\nRegenerate/validate the DAG before running Maven verification.`,
+                failureCategory: "verification-plan-stale",
+                durationMs: Date.now() - started,
+                ...{
+                    commandResults: staleResults.map((result) => ({
+                        ok: result.ok,
+                        exitCode: result.exitCode,
+                        failureCategory: result.failureCategory,
+                        command: result.command,
+                    })),
+                },
+            };
+        }
+    }
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    const timeoutMs = shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS;
+    const failFast = shell.failFast !== false;
+    const results = [];
+    const executedCommandKeys = new Set();
+    let beforeStatus;
+    let workspaceFingerprint;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        // Non-git cwd: skip write guard (documented limitation).
+        beforeStatus = undefined;
+    }
+    const reuseEligible = shouldReuseSuccessfulShellCommands(shell);
+    let commandContractKey;
+    let cache;
+    if (reuseEligible) {
+        try {
+            const governanceTaskId = meta.spec.sourceBinding?.taskId?.trim();
+            const checkpoint = await captureWorkspaceCheckpoint(input.cwd, {
+                ...(governanceTaskId ? { taskId: governanceTaskId } : {}),
+            });
+            workspaceFingerprint = checkpoint.fingerprint;
+        }
+        catch {
+            // Fingerprint unavailable: do not create cache / do not reuse.
+            workspaceFingerprint = undefined;
+        }
+        commandContractKey = buildShellCommandContractKey({
+            cwd,
+            timeoutMs,
+            envAllowlist: shell.envAllowlist,
+            failFast,
+            nonZeroExitPolicy: shell.nonZeroExitPolicy,
+            controllerInput: {
+                sourceBinding: meta.spec.sourceBinding,
+                taskContractBinding: meta.spec.taskContractBinding,
+                runtimeContract: meta.spec.runtimeContract,
+            },
+        });
+        const cacheKey = workspaceFingerprint
+            ? shellCommandCacheKey(meta.runId, workspaceFingerprint, commandContractKey)
+            : undefined;
+        const existing = cacheKey ? sameRunShellCommandCaches.get(cacheKey) : undefined;
+        if (existing && existing.runId === meta.runId && existing.contractKey === commandContractKey) {
+            cache = existing;
+        }
+        else if (cacheKey && workspaceFingerprint) {
+            cache = {
+                runId: meta.runId,
+                contractKey: commandContractKey,
+                workspaceFingerprint,
+                byCommand: new Map(),
+            };
+            sameRunShellCommandCaches.set(cacheKey, cache);
+        }
+    }
+    for (const command of commands) {
+        const commandNumber = results.length + 1;
+        // Cache each contractual occurrence independently. A result written for an
+        // earlier duplicate in this round must not satisfy a later occurrence.
+        const commandCacheKey = command;
+        const cached = cache?.byCommand.get(commandCacheKey);
+        if (cached && !executedCommandKeys.has(commandCacheKey)) {
+            const reusedAt = new Date().toISOString();
+            results.push({
+                command,
+                cwd: cached.cwd,
+                durationMs: 0,
+                wallDurationMs: 0,
+                executionDurationMs: cached.durationMs,
+                startedAt: reusedAt,
+                finishedAt: reusedAt,
+                sourceNodeId: cached.sourceNodeId,
+                sourceReceiptNodeId: cached.sourceReceiptNodeId,
+                exitCode: cached.exitCode,
+                failureCategory: cached.failureCategory,
+                ok: true,
+                stderr: cached.stderr,
+                stderrBytes: cached.stderrBytes,
+                stderrTruncated: cached.stderrTruncated,
+                stdout: cached.stdout,
+                stdoutBytes: cached.stdoutBytes,
+                stdoutTruncated: cached.stdoutTruncated,
+                timedOut: cached.timedOut,
+                reused: true,
+            });
+            continue;
+        }
+        const result = await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs,
+            envAllowlist: shell.envAllowlist,
+            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`),
+            },
+        });
+        results.push(result);
+        executedCommandKeys.add(commandCacheKey);
+        if (result.ok && cache) {
+            cache.byCommand.set(commandCacheKey, {
+                ok: true,
+                exitCode: result.exitCode,
+                failureCategory: "success",
+                stdout: result.stdout,
+                stderr: result.stderr,
+                stdoutBytes: result.stdoutBytes,
+                stderrBytes: result.stderrBytes,
+                stdoutTruncated: result.stdoutTruncated,
+                stderrTruncated: result.stderrTruncated,
+                timedOut: result.timedOut,
+                durationMs: result.durationMs,
+                startedAt: result.startedAt ?? new Date().toISOString(),
+                finishedAt: result.finishedAt ?? new Date().toISOString(),
+                sourceNodeId: input.task.id,
+                sourceReceiptNodeId: input.task.id,
+                cwd: result.cwd,
+            });
+        }
+        if (!result.ok && failFast)
+            break;
+    }
+    let writeGuardViolations = [];
+    let writeGuardOk = true;
+    if (beforeStatus !== undefined) {
+        try {
+            const guard = await runShellWriteGuard({
+                rootCwd: input.cwd,
+                task: input.task,
+                beforeStatus,
+            });
+            writeGuardOk = guard.ok;
+            writeGuardViolations = guard.violations;
+        }
+        catch (error) {
+            writeGuardOk = false;
+            writeGuardViolations = [
+                `git status unavailable: ${error instanceof Error ? error.message : String(error)}`,
+            ];
+        }
+    }
+    // Write-guard or workspace mutation invalidates same-run success reuse.
+    if (!writeGuardOk && reuseEligible && workspaceFingerprint && commandContractKey) {
+        sameRunShellCommandCaches.delete(shellCommandCacheKey(meta.runId, workspaceFingerprint, commandContractKey));
+    }
+    const commandsOk = results.every((result) => result.ok);
+    const recordNonZero = shell.nonZeroExitPolicy === "record";
+    const ok = (commandsOk || recordNonZero) && writeGuardOk;
+    const firstFailure = results.find((result) => !result.ok);
+    const receipt = {
+        schemaVersion: 1,
+        runId: meta.runId,
+        nodeId: input.task.id,
+        workspaceFingerprint: workspaceFingerprint ?? null,
+        failFast,
+        commands: results.map((result) => ({
+            command: result.command,
+            ok: result.ok,
+            exitCode: result.exitCode,
+            failureCategory: result.failureCategory,
+            startedAt: result.startedAt,
+            finishedAt: result.finishedAt,
+            wallDurationMs: result.wallDurationMs,
+            executionDurationMs: result.executionDurationMs ?? result.durationMs,
+            reused: result.reused === true,
+            reuseSource: result.reused
+                ? { nodeId: result.sourceNodeId, receiptNodeId: result.sourceReceiptNodeId }
+                : null,
+            subchecks: parseCheckRepoSubcheckDurations(result),
+        })),
+    };
+    await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "shell-command-receipt.json", receipt);
+    const summaryMarkdown = buildShellResultSummaryMarkdown({
+        nodeId: input.task.id,
+        runId: meta.runId,
+        rootCwd: input.cwd,
+        results,
+        writeGuardViolations: writeGuardOk ? undefined : writeGuardViolations,
+    });
+    const receiptMarkdown = [
+        summaryMarkdown,
+        "",
+        "## Same-run reuse receipt",
+        "",
+        `| workspaceFingerprint | ${workspaceFingerprint ?? "(unavailable)"} |`,
+        `| failFast | ${failFast} |`,
+        "",
+        "| # | ok | exitCode | reused | command |",
+        "|---|----|----------|--------|---------|",
+        ...results.map((result, index) => `| ${index + 1} | ${result.ok} | ${result.exitCode ?? "null"} | ${result.reused === true} | ${result.command.replace(/\|/g, "\\|")} |`),
+    ].join("\n");
+    await writeDagNodeTextArtifact(meta.runDir, input.task.id, "result.summary.md", receiptMarkdown);
+    const aggregate = summarizeCommandResults(results);
+    const stderrParts = [aggregate.stderr];
+    if (!writeGuardOk) {
+        stderrParts.push(`write guard failed: ${writeGuardViolations.join(", ")}`);
+    }
+    let failureCategory = "success";
+    if (!commandsOk) {
+        failureCategory = firstFailure?.failureCategory ?? "nonzero-exit";
+    }
+    else if (!writeGuardOk) {
+        failureCategory = "write-guard";
+    }
+    const commandResults = results.map((result) => ({
+        ok: result.ok,
+        exitCode: result.exitCode,
+        failureCategory: result.failureCategory,
+        command: result.command,
+        reused: result.reused === true,
+    }));
+    const recordPrefix = recordNonZero && !commandsOk
+        ? `nonZeroExitPolicy=record exitCode=${firstFailure?.exitCode ?? "null"}\n`
+        : "";
+    const reuseNote = results.some((result) => result.reused)
+        ? `same-run-reuse workspaceFingerprint=${workspaceFingerprint ?? "unknown"}\n`
+        : "";
+    return {
+        ok,
+        stdout: `${recordPrefix}${reuseNote}${aggregate.stdout}`,
+        stderr: stderrParts.filter(Boolean).join("\n\n"),
+        failureCategory,
+        durationMs: Date.now() - started,
+        // extra field consumed by node-execution if supported; also embedded in stdout marker
+        ...{ commandResults },
+    };
+}